Exception and error resolution

Two distinct types of exceptions occur during processing: exceptions and errors. Exceptions are resolvable errors that occur when Relativity cannot process a job or file. For example, a password-protected file where Relativity cannot find the password. In this case, you can resolve the issue by providing the password and rerunning the process. Errors occur when the processing engine cannot complete the job. For example, an error may occur when there is a break in network connectivity where Relativity cannot access file storage. In this case, the resolution is to rerun the processing job after you restore network connectivity. Other errors may be more complex and require support intervention.

For information on where to find processing exception and error information in RelativityOne, see Processing exception overview.

This page details the following:

• Types of processing exceptions
• Processing phases where exceptions may occur
• File exceptions
  • File exception actions
  • Resolving file exceptions
    • Retrying an exception from the processing set
      • Exception categories and their probability of retry success
    • Retry file exception mass action
    • Replacing a corrupted file
    • Resolving a password-protected file exception
    • Publish documents with field length exceptions
• Job errors
  • Job error workflow
  • Resolving job errors

Types of processing exceptions and errors

There are two types of processing issues that may affect the outcome of you processing job: file exceptions and job errors.

• File exceptions—affect a single file. Overall, the processing job continues, even if file exceptions exist. File exceptions are resolvable and have a status of Not Resolved in the Files tab. An example of a file exception might is a password-protected file where Relativity cannot find the password. By supplying the password you can retry the exception.
• Job errors—affect the entire processing job and block publishing. You must resolve job errors before you can continue processing.

Exception levels

Discover and publish exceptions are further defined by the exception level, which indicates severity of the issue. Each phase has two exception levels:

• Discover
  • Warning—the job continues; however, metadata may be missing.
  • Error—the job is blocked from completing.
• Publish
  • Warning—the job continues; however, metadata may be missing.
  • Error—the job is blocked from completing.

Processing phases where exceptions and errors may occur

Exceptions and 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 errors that occur during discovery are unresolvable, and you cannot retry them. You should always address unresolvable discover job errors. Not addressing unresolvable errors may result in missing documents or incomplete metadata in published documents. Address these errors by creating a new processing set (or sets) and rediscovering the data.
  • Text-extraction—job exceptions that are resolvable have an error status of Ready to retry. Retry the error from the same processing set.
• Publish—job exceptions during the publishing phase that are resolvable have an error status of Ready to retry. Retry the error from the same processing set.

File exceptions

After completing the discovery or publish phases, you notice the processing job encountered file exceptions. You want to investigate and resolve the exceptions to maximize the data published to your workspace.

File exception actions

You can take action on file exceptions from the mass actions drop-down menu located at the bottom of the Files tab page.

The following mass actions are available:

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 exceptions	This action provides the ability to resolve issues occurring during discover and publish. You can see these issues on the Current Files with Exceptions and All Files with Exceptions views within the Files tab. For details on how to retry exceptions from the Deleted Documents view in the Files tab, see Retrying delete exceptions. You must have edit permissions on the Discovered Files object to be able to retry file exceptions. Note the following regarding retrying exceptions: Auto-publish is not enabled when you retry exceptions. If you resolve any discover or text extraction exceptions, you must manually publish them into your workspace by navigating back to the processing set and clicking the Retry button. The discovery retry of exceptions 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 exceptions as these exceptions represent data not in review. If an exception occurs on a loose file during discovery, Relativity still attempts to publish it. For example, if a Password Protected exception 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 exceptions for a set when you retry any exception 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 exceptions with an exception Status of Not Resolved for retry.
Ignore exceptions	This provides the ability to set a file’s exception Status to Ignored, which removes it from the Current Files with Exceptions view. The record is visible in the All Files and All Files with Exceptions views.
Undo Ignore exceptions	Sets a file’s exception 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 exception, 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 exception 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 exceptions once completed. After uploading a new document, and you select Replace & Retry, the native file updates before you republish. The retry action for job exceptions only retries exceptions 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 exceptioned 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 exception 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 exceptioned files on the Files tab page.

Resolving file exceptions

The following sections describe actions you may take to resolve file exceptions.

Retrying an exception from the processing set

You can retry file exceptions from the processing set by clicking the Retry File exceptions button located in the Process Files console.

A confirmation message appears with information about the number of exceptions you are about to retry, along with the associated exception categories. Click Yes to proceed or Cancel to return to the processing set page.

Container file exceptions

File exceptions on container files, such as a .zip file, may result in missing data from one or more files within the container. In some cases, you may have many files in exception, even though you see a single file exception on the container. For container file exceptions, extract the files and then create a new processing set with the extracted files.

Exception categories and their probability of retry success

Relativity retries file exceptions that have a high chance of success. The exception category associated with the file determines the probability of success. exception 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 to the Password Bank or replacing corrupt files. The table below lists the types of exceptions that Relativity retries.

Exception 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

Retry file exceptions mass action

Starting from your processing set, perform the following steps:

1. From the Process Files console, click File exceptions to open the Current Files with Exceptions view. The list is automatically filters for your processing set.
2. You can filter the exceptioned files that are the most important to resolve. Some common filters are:
   • Exception Category—group issues of a similar type.
   • Exception 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.
3. Once you identify a group of records to resolve, select the Retry Exceptions mass action to begin the process. Alternatively, you can retry all exceptioned files without filtering.

You can now track the progress of the exception retry through the processing set's progress bar or by navigating to the Processing and Imaging Queue and viewing active jobs.

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.

Starting from your processing set, perform the following steps:

1. From the Process Files console, click File Errors to open the Current Files with Exceptions view. The list is automatically filters for your processing set.
2. Locate the file you need to replace. Common techniques are:
   • Filter the exception Category field for either Corrupted File or Corrupted Container.
   • Filter by specific file names.
   • Filter for specific exception messages.
3. Select the appropriate checkbox for the file you want to replace.
4. Select the Single Download/Replace option in the mass action drop-down menu.
5. From here, two options are available:
   • To download a corrupted file: confirm the modal displays the correct container and click the Download button.
   • To replace a corrupted file: drag the replacement file into the modal or select browse for files to locate the container.
6. 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.
7. 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.

For more information on replacement considerations, see Single Download/Replace.

Resolving a password-protected file exception

Some files are password-protected. If Relativity cannot find the password during the Discover phase, you will see an exception with the category, Password Protected Container. The resolution for this exception is to add the password to the Password Bank.

To add a password to the bank, perform the following steps:

1. Navigate to the Password Bank | Processing tab.
2. Click New.
3. Select Passwords for the Type value.
4. Add a meaningful description to help you differentiate between other password entries.
5. Add one or more passwords. You must enter each password on a separate line.
6. Click Save.
7. Retry the file exception from either the processing set Process Files console, or from the Files tab mass actions drop-down menu.

For completed details on storing passwords, see Password Bank.

Publish documents with field length exceptions

Note: Some functionality described in this topic has been released via a phased rollout, meaning that certain customers receive it before others. For that reason, you may be seeing documentation for features that you do not yet have in your Relativity instance. For more information on phased rollouts see the Phased Rollout FAQ on the Community.

When metadata exceeds the field length limit for optional fields, Relativity publishes the file, excluding the offending metadata, not as an error but as an exception warning. The published content is available for review or other downstream functions such as indexing and search terms reports. Files with metadata exceeding the field length limit for required fields have an exception error status where the entire file is held back and not published.

Resolving field length exception warnings

You cannot successfully retry field length exception warnings without some intervention. For example, suppose you have an optional email field with a field length of 250 characters and try to publish a file with an email containing 300 characters. You see the field length exception warning. You can change the email field length to 350 characters and retry the warning, resulting in the email metadata being published with its parent file.

You cannot change required (system-mapped) fields with a fixed-length text field type. In this case, Relativity displays an exception error, and you cannot publish the file in its current state. For example, Container Name is a system-mapped field with a maximum limit of 255 characters. If you exceed that limit, you will see an exception error. Since you cannot change the field properties, you must change the container name length to meet the field requirements. After that, you can retry the error.

Steps

1. Use the search bar to navigate to the Fields tab.
2. Use the Name filter to locate the field you want to change. You can also scroll through the field names if you are not sure of the field name. In the image below, we want to change the Email From field.
   
3. Click the field Name (in this example, Email From) to open the fields details.
4. Click Edit.
5. Change the Maximum Length field so that it exceeds the field characters that threw the exception.
   
6. Click Save.

Job errors

Navigate to the Job Exceptions tab to view a list of job errors. The Current Files with Exceptions view displays all outstanding job errors. The All Files with Exceptions view displays all job errors across time, regardless of their resolution. Review the exception Status and Message fields for an overview of the error and the potential for remediation. Is this correct? Do you view job errors from the Job Exceptions tab?

Job error workflow

The following diagram shows the job error workflows for Inventory, Discover, and Publish jobs.

Resolving job errors

The steps for resolving job errors depend on the phase running when the error occurred. For some phases, errors are unresolvable; others require creating and running a new processing set. You can resolve some errors using mass actions or by retrying the errors from the processing set. The first step in resolving job errors is determining the phase in which the error occurred.

To identify the phase where the error occurred, perform the following steps:

1. Navigate to the Job exceptions tab.
2. Click the Error Identifier for the error you are researching. The Job Error Details pane opens.
3. Click the Advanced tab.
4. Locate the Data section, then locate the Relativity.Processing.Error.Phase entry key. The key value is the phase where the error occurred. In the image below, the phase is Inventory.
   

Inventory

All inventory errors are unresolvable. You must address the error outside of Relativity, then rerun Inventory from the processing set.

To re-inventory files, perform the following steps:

1. From the processing set, click the Inventory Files button in the Process Files console.
2. A confirmation message appears. Click Yes.

When you rerun the Inventory phase, Relativity clears any errors from the previous job.

For detailed information on the Inventory phase and errors, see Inventory processing.

Note: When working with questionable data sets, run Inventory to get a pre-assessment of corrupt files. This way, you can review the error messages returned for possible remediation before continuing to other processing phases.

Discover

The Discover phase includes file discovery and text extraction. You should treat errors that occur during the Discover phase with high priority, as they are generally unexpected. Resolving these errors depends on where they occurred during the discovery process. Not resolving Discover errors may result in incomplete metadata when the files are published.

To address errors that occur during file discovery, perform the following steps:

1. If possible, retry the errors from within the processing set.
2. If the errors are unresolvable, create a new processing set using the same data source as the errored set.
3. Rerun Discover.

To address job errors that occur during text extraction, perform the following steps:

1. From the processing set, click the Job Errors link in the Process Files console.
2. You can retry errors with a status of Ready to retry. From the mass actions drop-down menu, select Retry Errors.
3. On the Retry error(s) confirmation dialog, click Retry.
   
   The status changes to Resolving. You can refresh the page until the status updates with either Resolved or Not Resolved. If the error is not resolved, you must rediscover the files from a new processing set.

For detailed information on discovering files, see Discovering files.

Publish

Job exceptions during the publishing phase that are resolvable have an exception status of Ready to retry. Retry the exception from the same processing set.

For detailed information on the Publish phase and exceptions, see Publishing files.