You may encounter errors from time to time while running processing jobs. Errors can occur during any processing phase, affecting single files or the entire processing job. This topic begins with an overview of processing error types before diving into more detailed information on error-specific views and fields you can use for error diagnosis and resolution.
This page contains the following information:
There are two error types: file-level errors and job-level errors.
- File-level errors—affect a single file. Overall, the processing job continues, even if file-level errors exist. Relativity marks some file-level errors as unresolvable, which means you cannot retry them through the originating processing set. Other errors are resolvable and have an error status of Ready to retry. Examples of unresolvable file-level errors might include corrupt files and password-protected files (where the Password Bank does not contain the correct password.) An example of a file-level error you can retry might be a network failure or timeout.
- Job-level errors—affect the entire processing job and block publishing. You must resolve job-level errors before you can continue processing.
Errors can occur during any processing phase, such as Inventory, Discover, and Publish.
- Inventory—all Inventory errors are unresolvable, and you cannot retry them. To address inventory errors, rerun Inventory from the same processing set.
- Discover—the Discover phase covers file discovery and text extraction.
- Discover—job-level errors that occur during discovery are unresolvable, and you cannot retry them. You should always address unresolvable discover job errors. Do this by creating a new processing set (or sets) and rediscovering that data. Not addressing unresolvable errors may result in incomplete metadata in published documents.
- Text-extraction—job-level errors that are resolvable have an error status of Ready to retry. Retry the error from the same processing set.
- Publish—job-level errors during the publishing phase that are resolvable have an error status of Ready to retry. Retry the error from the same processing set.
Job-level error workflow diagram
The following diagram shows the job-level error workflows for publishing and discovering jobs. Not all errors are resolvable from within the originating processing set. For example, you must create a new processing set to address job-level errors occurring during the Discover phase. In other cases, you can retry the error from the originating processing set, until the error either resolves or you discontinue the retry process.
Processing errors tabs
The Files and Job Errors tabs allow you to locate issues that may have occurred in any processing sets. Relativity notifies you of errors on the processing set page when the job completes.
The Files tab has all error information associated to specific files that have occurred during the discovery, publish, and deletion phases of processing. The Current Errored Files and All Errored Files views only contain information pertaining to errors.
- The Current Errored Files view displays all outstanding errors from processing jobs. This is your primary location for workflows like error retry, ignore, and file replacement.
- The All Errored Files view is primarily used for historical reporting of errors from processing sets. This view displays any file that encountered an error, regardless of its resolution. It may be helpful to export an error report for a collection or set of custodians for further review or reference.
For more information on these views, see Files tab.
Job Errors tab
The Job Errors tab displays all errors that occurred on processing sets run in your workspace. These errors are usually not associated with any specific files within a processing set, but rather to the entire set itself.
Job Error views
The Current Job Errors view in the Job Errors tab displays all unresolved job errors while the All Job Errors view displays any job error that has occurred throughout the lifecycle of the matter. Both views display the following fields:
- Error Identifier—the unique identifier of the error as it occurs in the database. When you click this message, you are taken to the error details layout, where you can view the stack trace and other information. Note that for Unresolvable errors, the console is disabled because you can't take any actions on that error from inside Relativity. For more information, see Processing error workflow.
- Error Status—the status of the error. This is most likely Unresolvable.
- Message—the cause and nature of the error. For example, "Error occurred while trying to overlay deduplication details. Please resolve publish error or republish documents from data source below. DataSource Artifact Id: 1695700".
- Custodian—the custodian associated with the data source containing the file on which the error occurred.
- Processing Set—the name of the processing set in which the error occurred.
- Data Source—the data source containing the file on which the error occurred.
- Error Created On—the date and time at which the error occurred during the processing job.
- Republish Required—the error must be retried in order to be successfully published.
- Notes—any manually added notes associated with the error.
Note: Errors occurring during inventory are always represented as Job Errors. For more information, see Inventory Errors.
Job Error layout
Clicking on the job error identifier value brings you to the Job Error Details screen.
Note that the Error Actions console is not available for unresolvable job errors, since you cannot retry or ignore job errors as you can with document errors.
To see the job error's stack trace, click on the Advanced tab of the error details layout and view the value in the Stack Trace field.
Useful error field information
The following sections provide information on error-specific fields and views that you can use in your processing workflow.
Combined error fields
The Files tab displays a single error associated to a file.
This error displays through the Error Message, Error Category, Error Phase, and Error Status fields. However, a single file can have multiple errors at the same time as issues can occur during different phases of Processing. Relativity determines the displayed error based on a set precedence of Processing phases that can potentially block content from being published. The precedence is as follows:
Delete—a deleted document encountered an issue, potentially affecting recalculation of deduplication.
Publish—a document was not promoted to review due to an error.
Discover –a file may have encountered an issue during expansion and may not have extracted a child record or associated metadata.
Text Extraction—a file encountered an issue during text extraction and is missing some or all associated text.
Error status information
The Error Status field provides information on where the file is in error remediation.
The error status value helps in determining if you need to take action on a file, or to see if the file had previous errors. When a file has all its errors resolved, the Error Message, Error Category, and Error Phase fields no longer display any content. However, the Error Status field displays Resolved to indicate that the file had issues that are now resolved. Error status values include:
Not Resolved—the error is still outstanding.
Resolving—the error is in the process of being retried.
Ignored—error ignored. See File error actions.
Error Category list
The Error Category field provides insight into the nature of the errors that have occurred during processing.
The following table provides a listing of all values on the Error Category field, along with a description of what kinds of issues those values bring back if filtered.
These errors are exclusive to container files that have encountered corruption when attempting to open and locate files within the container itself. When containers have these errors associated to them, you will not see any extracted loose files. The errors are either ignored or downloaded offline for you to investigate whether the corruption is fixable, then subsequently replaced and retried.
|Corrupt File||These errors are exclusive to non-container files that have found elements of corruption during Processing. The errors are either ignored or downloaded offline for you to investigate whether the corruption is fixable, then subsequently replaced and retried.|
|Could Not Identify||Relativity Processing could not identify the file during discovery. The file may be corrupt, but an exact cause was not known at the time of discovery.|
|Environmental||Environmental errors are a result of issues in the Relativity Processing environment. Retry and resolve these errors when encountered.|
|File Read / Write Error||These errors are a subset of Environmental issues specifically caused by file system issues. Retry and resolve these errors when encountered.|
Relativity could not extract an attachment from a document or email from its file.
|Missing File Metadata||A file is missing a piece of metadata.|
|Missing Extracted Text||These errors represent issues that occurred during Text Extraction jobs that have caused a file to be missing some or all associated text. Relativity could not identify a root cause. Retry and resolve the errors where possible.|
|Partially Corrupted Container||These errors are exclusive to container files that have encountered corruption during extraction of specific records. When containers have these errors associated to them, you may see some files extracted, but not all. The errors are either ignored or downloaded offline for you to investigate whether the corruption is fixable, then subsequently replaced and retried.|
|Password Protected Container||
These errors are exclusive to container files that have encountered some form of password protection or encryption security measures. You must add the password or encryption key to the Password Bank to resolve the error. For more information, see Password Bank.
Note: When investigating publish errors, if you see five password protected errors associated with an .msg file, but the email and all its contents opens and displays correctly in the viewer, the email had a password-protected container attached.
|Password Protected File||These errors are exclusive to non-container files that have encountered some form of password protection or encryption security measures. You must add the password or encryption key to the Password Bank to resolve the error. For more information, see Password Bank.|
|Relativity Field Configuration||These errors represent issues with Field Mapping during publish jobs. They are usually associated to a specific setting like length or an Associative Object Type. Resolve the field settings errors according to the error message.|
|Unsupported||Relativity Processing cannot obtain metadata or text from unsupported files. You can publish the files to your workspace, but they may not be accessible from the viewer.|
You can view file details by clicking the Show details for this file icon ( .) Details include file data, file metadata, and content metadata.
Click the Processing Errors tab to view a summary of errors, and the error history.
- The Error History section represents all errors that have ever occurred on a file. This acts as a timeline of the record’s errors, showing when they occurred, what they were about, and if any are still active. This includes errors resulting from retries of previous errors and contains category, phase, date/time, and message information. All times are kept in UTC format.
The Error Summary section displays a count of all active errors along with their associated category and phase. This is especially important when investigating errors relating to container files, as there can be many associated to the parent container during file extraction. This helps determine the level of impact the issue has as it may affect many files originating from it.
Pivotable error fields
By default, all relevant processing error fields are available to group by and pivot on in the Current Errored Files and All Errored Files views of the Files tab.
For descriptions of all the fields available for Pivot, see the Files tab.
You can take action on file errors from the Processing Set page or from the mass operations available on the Files tab.
Processing Set error retry
You can retry file errors within the Processing Set by using the Retry File Errors button located under the Processing Set console on the right-hand side of the page.
A confirmation message pops up reminding you of the errors you are about to retry. Click Retry to proceed or Cancel to return to the processing set layout.
Relativity retries file errors that have a high chance of success. The error category associated with the file determines the probability of success. Error categories such as Corruption or Password Protection are not retried as they are not likely to be successful without manual intervention (for example, adding passwords or replacing a corrupt file). The table below lists the types of errors that Relativity retries.
|Error Category||Included in Retry Button|
|Could Not Identify||No|
|File Read/Write Issue||Yes|
|Missing child items due to password protection||No|
|Missing Extracted Text||Yes|
|Missing File Metadata||Yes|
|Partially Corrupted Container||No|
|Password Protected Container||No|
|Password Protected File||No|
|Relativity Field Configuration||No|
Files tab error actions
From the Files tab, you can take action on your errored files through the mass operations view.
|Export as CSV||This exports the list of processing errors as a CSV file.|
Gives you the option of republishing errored files after you resolve the erorrs. If the republish is successful, the files are available in the Documents list and removed from the Current Errored Files view.
For details on how to republish files from the Files tab, see Republishing files.
This action provides the ability to resolve issues occurring during discover and publish. You can see these issues on the Current Errored Files and All Errored Files views within the Files tab. For details on how to retry errors from the Deleted Documents view in the Files tab, see Retrying delete errors.
|This provides the ability to set a file’s Error Status to Ignored, which removes it from the Current Errored Files view. The record is visible in the All Files and All Errored Files views.|
|Undo Ignore Errors||Sets a file’s Error Status field back to its original value after you previously ignored it.|
|Single Download / Replace||
Use the Single Download / Replace mass operation to download a file to your local machine for investigation. After fixing the error, you can use the same mass operation to replace the original file with a newer version.
Note the following regarding downloading and replacing files:
For more information on the Single Download / Replace mass operation, see Single Download / Replace on the Files tab page.
Use the Download mass operation to download multiple errored files to your local drive.
Note the following regarding the downloading mass operation:
For more information on the Download mass operation, see Mass download errored files on the Files tab page.
The following mass operations are available:
Error resolution workflows
File error remediation
You have completed discovery or publish on your processing set and noticed that it had encountered some errors. You want to investigate and resolve those errors quickly so you can get all possible data into your workspace. Starting from your processing set, perform the following steps:
On the right-hand side of the page under Links, select File Errors to go directly to the Current Errored Files view on the Files tab. Automatic filtering takes you to the files in the previously viewed processing set.
On the Files tab, you can filter the errored files that are the most important to resolve. Some common filters are the following:
Error Category—group issues of a similar type.
Error Phase—groups issues occurring during a particular part of processing.
Custodian—when you have a priority Custodian you want investigated first.
Sort Date—to retry files within the matter's relevant date range.
Once you identify a group of records to resolve, select the Retry Errors mass action to begin the process. Alternatively, you can retry all errored files without filtering.
You can now track your progress of the error retry through the processing set page’s progress bar or by navigating to the Worker Monitoring page in Home mode.
For more information on Worker Monitoring, see Processing Administration.
Replacing a corrupted file
Sometimes, files reach processing in a corrupted state. Here is a workflow to replace corrupted files with non-corrupted versions so you can get the most out of your data. This works on encrypted documents as well.
Note: For more information on replacement considerations, see Single Download / Replace.
Starting from your processing set, perform the following steps:
On the right-hand side of the page under Links, select File Errors to go directly to the Current Errored Files view on the Files tab. Automatic filtering takes you to the errored files in the previously viewed processing set.
Locate the file you need to replace. Common techniques are:
Filter Error Category for Corrupted File or Corrupted Container.
Filter by specific file names.
Filter for specific error messages.
Select the appropriate checkbox on the left-hand column of the view.
Select the Single Download / Replace option in the mass action menu.
From here, two options are available:
Select the download button to inspect or repair your container.
Drag the replacement container into the modal or select browse for files to locate your container.
Once you add the replacement file to the modal, it automatically uploads to Relativity. A quick verification process lets you know if there are any issues or if there are any significant differences between the original and replaced files.
Select the Replace & Retry button to complete the replacement and retry any Discovery related errors.
Note: When replacing a file, the metadata associated with the new file overwrites any metadata associated with the original file. For example, if the original file's author is Steve Bruhle and the replacement file's author is Dave Crews, the metadata in Relativity displays Dave Crews.
Required security permissions
The following security permissions are required to perform actions on file errors:
|Object Security||Tab Visibility|
The following security permissions are required to perform actions on job errors:
|Object Security||Tab Visibility|
For more information on permissions, see Workspace permissions.