Processing error workflow

Errors can occur during your processing job, and Relativity provides a number of objects to make it easy to identify and address them, including the Document and Job Errors tabs and the Current Category field, among others.

Once you identify an error, you can then use the Error Actions console available on the error details layout to retry or ignore that error, depending on your current needs.

This page contains the following information:

Required permissions

You must have the Download and upload files with processing errors permission checked for the Processing Error object in the workspace security console if you want to be able to use the Error Actions console to download the affected file and then upload the replacement file.

If you’re a system admin, you need to be a member of a group that has this permission checked in order to use this feature. It doesn’t come by default with system admin permissions.

(Click to expand)

If you don't have this permission checked, then you'll only be able to use the Retry and Ignore/Un-ignore options on the console.

For more information on using the console, see Using the processing error console.

Processing errors tabs

The Document Errors and Job Errors tabs allow you to easily locate document and job errors, respectively, that occurred in any processing sets in your workspace.

 

Document Errors tab

The default Current Document Errors view in the Document Errors tab provides the following fields:

(Click to expand)

The Document Errors view provides the following fields:

  • File ID - the number value associated with the error file in the database.
  • Current Status - the current status of the error. You'll see any of the following values here:
    • In progress - the error is in progress for being ignored or retried.
    • Ready to retry - you're able to retry the error. You can only take action on an error if it has a status of Ready to Retry.
    • Unresolvable - you can't resolve the error by attempting to retry it.
    • Ignored - you ignored the error.
    • Retried - you retried the error and it is finished retrying.
    • In queue - the error is in the processing queue for retry.
    • Canceled - the error has been canceled by virtue of the processing job being canceled.
    • Ignored; Canceled - Relativity ignored the error and canceled the processing set.
    • Resolved - Relativity successfully retried the error after you addressed it, whether you did so by repairing the file outside of Relativity, providing a password to the password bank, or fixing an environmental issue.
  • Current Category - the system-assigned category of the error. This will display one of the following values:
    • Application Issue - the error was most likely caused by a third-party exception or issue outside of Relativity's control, or by a Relativity code problem.
    • Can't Open File or Part of File - the error occurred because an issue inside the file itself prevented Relativity from opening it.
    • Environmental Issue - the error was caused by an issue with the worker, whether it has to do with hardware, software, network connectivity, server configuration, etc.
    • Failed Import - the error was due to an issue with the Relativity import action.
    • General - the error, although analyzed already, still doesn't have enough information to be assigned a category.
    • Password Protected - the error occurred because the file is encrypted with a password that is not a valid entry in the Password Bank.
    • Potential Corrupt File - the error is most likely due to the file being corrupt.
    • Relativity Configuration - the error is due to an issue with the admin user settings in Relativity.
    • Uncategorized - the error does not have a corresponding category.
  • Current Error Message - the cause and nature of the error. When you click this message, you're taken to the error details layout, where you can use the error console to address the error. For more information, see Processing error workflow.
  • Source Location - the source path in which the file that has the error resides.
  • Number of Retries - the number of times a user has clicked Retry on this error.
  • 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.
  • Processing Data Source - the data source containing the file on which the error occurred.

Note the following details about how Relativity displays a processing error:

  • If a processed file contains more than one error, only the error that was first encountered on that file and currently has a status of ready to retry is listed in the document errors view.
  • When you retry the error listed, you are actually retrying all of the other errors that occurred on that file, as well, even though they aren't currently visible in the view.
  • If you successfully retry the error listed, then the next ready-to-retry error on that file will be displayed.
  • The Number of Retries field reflects the number of times a user has clicked Retry on an individual error and not the grand total of retried errors associated with that file.

Pivotable error fields

By default, the following processing error fields are available to group by and pivot on in the Document Errors view:

  • Current Category - the current category assigned to a processing error.
  • Current Status - the current status of the processing error.
  • Error Identifier::Category - all possible categories of processing errors.

  • Error Identifier::Error created on - the date and time at which the error was created by the system.
  • Error Identifier::Error status - the status of the error.
  • Error Identifier::Identified file type - all of the file types that received errors in the processing set. For example, ZIP compressed archive, Encrypted Office Document, 7z archive, etc.
  • Processing Data Source - the data source containing the file on which the error occurred.

Document Errors layout

When you click on the Current Error Message field from either the processing set or the Document Errors tab, you open up that error's details layout.

The Document Error Details layout provides the following fields:

  • Processing Data Source - the data source containing the file on which the error occurred.
  • Processing Set - the name of the processing set in which the error occurred.
  • Custodian - the custodian associated with the data source containing the file on which the error occurred.
  • Source location - the full name of the repository containing the processed files.
  • File ID - the number value associated with the error file in the database.
  • Current Category - the system-assigned category of the error. This will display one of the following values:
    • Application Issue - the error was most likely caused by a third-party exception or issue outside of Relativity's control, or by a Relativity code problem.
    • Can't Open File or Part of File - the error occurred because an issue inside the file itself prevented Relativity from opening it.
    • Uncategorized - the error does not have a corresponding category.
    • Environmental Issue - the error was caused by an issue with the worker, whether it has to do with hardware, software, network connectivity, server configuration, etc.
    • Failed Import - the error was due to an issue with the Relativity import action.
    • General - the error, although analyzed already, still doesn't have enough information to be assigned a category.
    • Password Protected - the error occurred because the file is encrypted with a password that is not a valid entry in the Password Bank.
    • Potential Corrupt File - the error is most likely due to the file being corrupt.
    • Relativity Configuration - the error is due to an issue with the admin user settings in Relativity.
  • Number of Retries - the number of times a user has clicked Retry on this file.
  • Current status - the state of the error:
    • In progress - the error is in progress for being ignored or retried.
    • Ready to retry - you're able to retry the error. You can only take action on an error if it has a status of Ready to Retry.
    • Unresolvable - you can't resolve the error by attempting to retry it.
    • Ignored - you ignored the error.
    • Retried - you retried the error and it is finished retrying.
    • In queue - the error is in the processing queue for retry.
    • Canceled - the error has been canceled by virtue of the processing job being canceled.
    • Ignored; Canceled - the error was ignored and the processing set was canceled.
  • Document - the Control Number of the document on which the error occurred.

Note: This field will be blank if the corresponding processing set has not been published.

  • Notes - any notes that you've added to the error via the Edit Notes option on the console or the Edit Notes mass operation.

Click the Other Details tab to see the following information:

  • Storage ID - the unique identifier of the file on the storage database.
  • Document File Location - the path to the file, which includes the actual file ending with the .doc file extension.

Document-level error workflow

Job Errors tab

To see any job-level errors that occurred in your workspace, navigate to the Job tab.

 

The Current Job Errors view in the Job Errors tab provides the following fields:

  • Error Identifier - the unique identifier of the error, as it occurs in the database. When you click this message, you're 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.
  • 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 Status - the status of the error. This will most likely be Unresolvable.
  • Message - the cause and nature of the error. For example, "Error occurred when attempting to open the ZIP file. Failed."
  • Notes - any manually added notes associated with the error.
  • Error Created On - the date and time at which the error occurred during the processing job.

Job Error layout

Clicking on the job error identifier value brings you to the Job Error Details layout.

Note that the Error Actions console is disabled for unresolvable job errors, since you can't retry or ignore job errors the way you can 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.

Job-level error workflow

Error categories list

The Current Category field provides a number of category values that provide insight into the nature of the errors that have occurred on your processed files.

The following table provides a listing of all values visible on the Current Category field, along with a description of what kinds of errors those values will bring back if you filter on them.

Category name Description
Application Issue

The error was most likely caused by one of the following:

  • Third party exception or issue outside of Relativity's control
  • Internal (Relativity) code problem
Can't Open File or Part of File The error occurred because the file or something within the file could not be opened.
Uncategorized These errors have not been assigned a category.
Environmental Issue Any error caused by an issue with the worker, whether it has to do with hardware, software, network connectivity, server configuration, etc.
Failed Import There was an issue with the import action.
General General errors are those that, although analyzed already, still lack enough information to be assigned a category.
Password Protected The error occurred because the file is encrypted with a password that is not a valid entry in the Password Bank.
Potential Corrupt File The error most likely was caused because the file is corrupt.
Relativity Configuration Admin user changes are required within Relativity software.

Error message list

The Current Error Message field provides a number of message values to describe the nature of the error that has occurred on your processed files.

Use the following link Processing Errors to view a table to find many of the error messages you could see in Relativity as a result of running a processing job, along with their error type and possible resolutions. To filter the data in the table, select a value from a dropdown in the column header (Message, Description, or Type) or type in the Search field. To sort, click the column name. Note that these aren't all the error messages possible in Relativity and that the following resolutions may not address the root cause of the corresponding errors in all cases. If you attempt these resolutions and the errors persist, contact Relativity Support for further assistance.

Identifying and resolving errors by category

To identify a document error by its current category, perform the following steps:

  1. Navigate to the Document Errors tab.
  2. In the Current Document Errors view, navigate to the Count of Current Category widget.
  3. In the pie chart, select the category of error you'd like to address. In the following example, we've selected one of the more common categories, Password Protected.
  4. Once the view narrows down the item list to only files containing Password Protected errors, select the specific error you need to address from the item list by clicking either the File ID value or the Current Error Message value.
  5. Once you open the error, use the Error Actions console to resolve it. For details on resolving the error through the Error Actions, see Using the processing error console.

Using the processing error console

When you open a document error, you can use any of the following options on the Error Actions console to address the error.

Note: You must have the Download and upload files with processing errors permission checked for the Processing Error object in the workspace security console in order to see the Download File and Upload Replacement File options on the console.

Note that the Download File and Upload Replacement File buttons are visible on the Error Actions console only if:

  • The user is part of a group that has the Download and upload files with processing errors permission enabled
  • At least one processing error on the document error meets all the following criteria:
    • Status is ready to retry
    • Document file location is set
    • Phase is discovering files or extracting data

  • Edit Notes - brings up a window in which you can enter notes to be applied to the error. Once you enter the desired notes, click Save Notes to apply them to the error. You can edit notes for multiple errors through the Edit Notes mass operation available on the document errors view. For more information, see Mass editing notes.
    • The Notes field is open to association and corresponds to the system-created Processing Errors::Notes field, which is associated with the Document object. The notes you enter are displayed on any view that you add this field to. You can display these notes on a document coding layout if you add the Processing Errors object as an associated object list to the Document object layout.
  • Retry - retries all the errors attached to the document.
  • Ignore - marks Ready-to-Retry errors attached to the document or job as Ignored.
    • When Relativity finishes marking the error as ignored, the Ignore console button changes to Un-ignore. Clicking Un-ignore marks all of the Ignored errors attached to the document or job as Ready to Retry.

    • When you click Un-ignore, you are presented with a confirmation message. Click Unignore again to proceed.

  • Download File - download the file containing the document errors. Once you download the file, you can address the error to repair the file. For example, if the error was due to password protection because you didn't previously provide that password in the Password Bank, enter it now to decrypt the file and then save the decrypted file to your local machine so that you can upload it here.
  • Upload Replacement File - uploads a new file to replace the file on which the document error occurred.
    • When you click the click to select a file link and then select the intended replacement file, Relativity begins to upload it.
    • If you upload a file type that is not supported, and you see the following error, either click Upload New Document to return to your file explorer or click Cancel to return to the error layout.
    • You must upload a file of the same extension as the file you downloaded or you will receive the following error. If you receive this error, either click Upload New Document to return to your file explorer or click Cancel to return to the error layout.
    • Once your document upload is successful, Relativity provides the following message.

Viewing error-related audits

Relativity audits the actions you take on processing errors, and you can view them via the View Audit button on the processing error layout. When you open the audit view, you can see such actions as File Download and File Upload, along with the processing error file download and replacement paths, among other details.

You can also access audit information through the History tab by filtering on the Object Type field for ProcessingError and on the Action field for File Download and/or File Upload.

Special considerations

The following sections provide information on specific error workflows that you may need to perform as part of your use of processing.

Bulk import error handling

You have options for handling bulk import errors, which previously caused your publish job to become suspended.

For each of the following scenarios, Relativity throws a document-level error and publishes the rest of the documents successfully. You can resolve those doc-level errors at your leisure while the files that don’t contain the following issues are published to the workspace:

  • Long folder name
  • Extracted text that is larger 2GB
  • Missing extracted text (whether deleted by a user or removed by anti-virus tool)

Non-existent document identifier errors

If you’re seeing a job-level publish error that states “This document identifier does not exist in the workspace – no document to overwrite,” it’s most likely due to any of the following issues:

  • Your workspace contains at least one published document with errors that you haven’t fixed, and the document that Relativity is trying to update with the duplicate custodian information was never imported. In this case, you need to fix the outstanding publish errors and retry that job level error.
  • You deleted the original published documents, perhaps because you determined that they were irrelevant. In this case, you can either disregard the error or re-process the data in a new workspace.
  • You modified the control numbers of the original published documents. In this case, you can either disregard the error or re-process the data in a new workspace.

Timeout errors for stuck workers

The LongRunningJobTimeout setting enables Invariant to terminate some stuck jobs. Specifically, this value determines the amount of time (in milliseconds) that a worker will work on a job before Invariant terminates that job. The default value is 180,000 milliseconds (30 minutes).

You may want to adjust this value if you have large documents that need additional time for processing, or if you need a shorter feedback loop. If you need to adjust this value, you can manually go into the AppSettings table and increase it accordingly. Previously, Invariant workers could get into a state in which they no longer reported progress and no longer completed work, which then required manual intervention to terminate those processes. When Invariant uses the LongRunningJobTimeout setting to stop a job, Relativity provides an error message to the processing user informing them that the timeout limit was reached.

Publish Batch ID field

The Publish Batch ID field is available to add to a processing error view. This field provides an identifier for the batch of documents that received a job-level error during publish.

Linking child errors to parent documents

Discovery errors are linked to parent documents in the Document Errors tab, which makes it easy for you to determine which errors broke families when errors have occurred on child containers. To locate these errors, refer to the following fields in Relativity:

  • Relativity Parent Document Identifier - the identifier of the file that contained the child document on which the error occurred. You can find this field on the Discover Errors - Unpublished Child Documents view in the Document Errors tab.
  • Discover Errors on Child Documents - a multi-object field that displays all errors that occurred during discovery on all children of published parent documents. Note that you must add this field to a document view.

Agent errors

During any phase of your processing job, you may encounter an agent error listed in connection to one or more data sources in the status section of the processing layout.

To address an agent error, navigate to the Agents tab and make sure that the agent being used in this processing job is enabled. If it isn't, you can restart it individually or click the Restart Disabled Agents option. For details, see Agents.

Mass ignoring errors

You have the option of ignoring errors you aren't going to resolve immediately and want to filter out of your list view. Ignoring errors is a viable option when an Office document is password protected and you don’t have the password and/or you haven't entered the password in the password bank.

You must have edit permissions for processing errors in order to ignore errors.

Note: You can't ignore job-level publishing errors.

To mass ignore errors:

  1. Navigate to the Document Errors tab.
  2. Select the check box next to each error you want to ignore. You can only ignore errors with a status of Ready to retry.
  3. Move to the mass operation menu in the bottom left corner, select Ignore. You can only ignore errors through this mass operation.

  4. Click Ok on the following confirmation message: “X errors are eligible to be ignored. Once you ignore these errors you can’t retry them until you have un-ignored them.”
  5. Once you've ignored the selected errors, check the Error status column for each error in the view. This status should be Ignored.

Mass un-ignoring errors

You can un-ignore errors that you previously ignored so that you can have the option of retrying them. You must have edit permissions for processing errors in order to un-ignore errors.

To un-ignore errors:

  1. Navigate to the Document Errors tab.
  2. Select the check box next to each error you want to un-ignore. You can only un-ignore errors that have a status of Ignored.
  3. Move to the mass operation menu in the bottom left corner and select Un-ignore. You can only un-ignore errors through this mass operation.

  4. A confirmation appears stating, “X errors are eligible to be un-ignored. Once you un-ignore these errors, they will be ready to retry.” Click Ok.
  5. Once the selected errors have been un-ignored, check the Error status column for each error in the view. This status should be Ready to retry.

Mass retrying errors

When processing errors are eligible for retry, you must resolve those errors outside of Relativity in the files themselves and then return to Relativity to retry them if you want those files to be published.

Once you've resolved the errors that occurred in the documents that you previously attempted to process, you can return to the Errors tab in Relativity and retry those errors through the Retry mass operation. You must have edit permissions for processing errors to retry them. Errors resulting from discovery remain in their current state while you publish files. These errors are available for retry after publish is complete.

Note the following regarding retrying errors:

  • Auto-publish is not enabled when you retry errors. If any files are successfully retried, you need to manually publish them into your workspace.
  • You should always resolve all publish errors with status of Ready to retry, as these errors mean that Relativity and the processing engine are out of sync in regards to the published data they’re referencing. A variety of issues could result from this un-synced state.
  • If an error occurs on a loose file during discovery, Relativity still attempts to publish it. Specifically, if you send discovered files to be published prior to resolving errors, those errors remain unresolved and Relativity ignores them when publishing documents. Relativity automatically retries all Publish errors for a set when you are republishing that set.
  • Once an error retry is submitted to the processing engine for a single processing set, another retry job for the same set cannot be submitted until the first retry is complete. The subsequent retry is placed in the queue in Relativity to await retry.

To mass retry one or more errors:

  1. Navigate to the Processing Errors tab.
  2. Select the check box next to each error you want to submit for retry.
  3. Select Retry from the mass operations menu in the bottom left corner. You can only retry errors with a status of Ready for retry.

  4. Click Ok on the confirmation window.

    • A retry is audited.
    • If a retried error has a status of In progress, you can’t delete the processing set containing that error.

Mass editing notes

You can apply notes to multiple document errors at the same time through the Edit Notes mass operation.

The Notes field is open to association and corresponds to the system-created Processing Errors::Notes field, which is associated with the Document object. The notes you enter are displayed on any view that you add this field to. You can display these notes on a document coding layout if you add the Processing Errors object as an associated object list to the Document object layout.

If you mass edit notes for errors that already contain notes, the existing value in the Notes field will be overwritten.

To mass edit notes:

  1. Select all document errors to which you'd like to apply notes.
  2. Select Edit Notes from the mass operations drop-down.
  3. Enter the desired notes in the text window and click Save Notes.