Processing error workflow

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:

Error types

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.

Error phases

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.

Files tab

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.
Resolved—error resolved.
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.

Category name	Description
Corrupt Container	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.
Missing Attachment	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.

Details modal

You can view file details by clicking the Show details for this file icon ( Expand details 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.

File error actions

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
Corrupt Container	No
Corrupt File	No
Could Not Identify	No
Environmental	Yes
File Read/Write Issue	Yes
Missing Attachment	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
Unsupported	No

Files tab error actions

From the Files tab, you can take action on your errored files through the mass operations view.

Mass operation	Description
Export as CSV	This exports the list of processing errors as a CSV file.
Republish	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.
Retry Errors	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. You must have edit permissions on the Discovered Files object to be able to retry file errors. Note the following regarding retrying errors: Auto-publish is not enabled when you retry errors. If you resolve any discover or text extraction errors, you must manually publish them into your workspace by navigating back to the processing set and clicking the Retry button. Not all errors reported in the discovery process are resolvable. This is because processing reports all the issues it encounters through an error. The discovery retry of errors process has a longer timeout period than the initial discovery process. It is not uncommon for the retry process to run longer than the initial discovery process. You should always resolve all publish errors as these errors represent data not in review. If an error occurs on a loose file during discovery, Relativity still attempts to publish it. For example, if a Password Protected error occurs on a PDF file during discovery, you can still publish the file in its current state. The resulting record may have metadata or extracted text missing depending on the issue, but still referenced during review. Relativity automatically retries all publish errors for a set when you retry any error within that set. Do not work on multiple retry attempts simultaneously. If you submit a secondary retry while the initial retry is still in progress, the second retry waits in a queue until the first retry completes. You can only submit errors with an Error Status of Not Resolved for retry.
Ignore 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: You can only download or replace a single file at a time. You can only perform these actions on files with an error status of Not Resolved. There is no file size limitation when downloading files. There is a one-gigabyte file size limitation when uploading replacement files. Performing a file replacement retries associated errors once completed. After uploading a new document, and you select Replace & Retry, the native file updates before you republish. The retry action for job errors only retries errors in a Ready to Retry state. For more information on the Single Download / Replace mass operation, see Single Download / Replace on the Files tab page.
Download	Use the Download mass operation to download multiple errored files to your local drive. Note the following regarding the downloading mass operation: You can only use the Download mass operation on files with an error status of Not Resolved. When complete, files are packaged in a zip container and saved to your local drive. You must use the Single File / Replace mass operation to replace a file. There is a 2.14 GB limitation on the zip container file size. 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
Discovered File - View, Edit Download and Replace files with processing errors	Processing Files

The following security permissions are required to perform actions on job errors:

Object Security	Tab Visibility
Job Error - View, Edit Processing Error - View, Edit	Processing Job Error

For more information on permissions, see Workspace permissions.