# Handling Exceptions

| Minimum Version | R2 2020 |
| --------------- | ------- |

**RadPdfProcessing** has an exception handling mechanism. It allows you to intercept and handle exceptions when the document is imported or loaded. This functionality introduces the following events:

| Event                                                | Description                                                                                                                                                                     |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PdfImportSettings.DocumentUnhandledException`       | Fired when an exception occurs during document import. If `ReadingMode` is `AllAtOnce`, the entire document is loaded on import and this event covers the full load.            |
| `RadFixedDocument.DocumentUnhandledException`        | Fired when an exception occurs while loading document pages. Raised when the document is imported with **OnDemand** `ReadingMode` and a particular page is loaded after import. |
| `PdfExportSettings.DocumentUnhandledException`       | Fired when an exception occurs while exporting document pages. Introduced in **Q1 2025**.                                                                                       |
| `SkiaImageExportSettings.DocumentUnhandledException` | Fired when an exception occurs while exporting a PDF page. Introduced in **Q3 2025**. *(Available in the .NET Standard version of the libraries.)*                              |

When the events are raised, the `DocumentUnhandledExceptionEventArgs` argument is passed. This argument contains the following properties:

| Property    | Description                                                                                                                                                                                                                             |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Exception` | Gets the document exception.                                                                                                                                                                                                            |
| `Handled`   | Gets or sets whether the exception is handled. The initial value is `false`, except for `InvalidStructureTreeException` when `PdfImportSettings.InvalidStructureTreeHandling` is `Continue`. In that case, the initial value is `true`. |

> note The exception handling mechanism handles exceptions at the very beginning of the import as well. In such a case, the event is raised and an empty document instance is returned. The exception handling mechanism **does not handle** exceptions while parsing **fonts glyph data** or parsing **images** during document rendering in the UI viewers.

## Using ImportSettings.DocumentUnhandledException

To use this functionality, handle the `PdfImportSettings.DocumentUnhandledException` event. The `Handled` property in the event arguments indicates whether the exception is handled by the code in the event handler or the exception is thrown.

```C#
PdfFormatProvider provider = new PdfFormatProvider();
provider.ImportSettings.ReadingMode = ReadingMode.AllAtOnce;
provider.ImportSettings.DocumentUnhandledException += (s, e) =>
{
    Debug.WriteLine("The document is corrupted and cannot be loaded: " + e.Exception.Message);
    e.Handled = true;
};
RadFixedDocument document = provider.Import(File.ReadAllBytes("SampleDoc.pdf"), TimeSpan.FromSeconds(10));
```

## Handling Invalid Structure Trees

The structure tree describes the logical structure of a tagged PDF document. Use `PdfImportSettings.InvalidStructureTreeHandling` to control how import responds to malformed structure-tree entries.

The `InvalidStructureTreeHandling` enum provides two options:

* `Continue` (default): Reports `InvalidStructureTreeException` through `PdfImportSettings.DocumentUnhandledException` with `Handled` initially `true`. Import skips invalid entries and continues, even without an event handler.
* `Throw`: Reports the exception through the same event with `Handled` initially `false`. Import throws the exception unless an event handler sets `Handled` to `true`.

The provider reports only the first `InvalidStructureTreeException` per document import, not one event for every skipped entry. If `IgnoreMarkedContent` is `true`, import skips the structure tree entirely.

> important Import does not repair invalid entries. The imported structure tree may be incomplete even when page content imports successfully.

## Using RadFixedDocument.DocumentUnhandledException

When you use the **OnDemand** reading mode, handle the `RadFixedDocument.DocumentUnhandledException` event. The `Handled` option in the event arguments indicates whether the exception is handled by the code in the event handler or the exception is thrown.

**Using the DocumentUnhandledException Event While Loading on Demand**

```C#
PdfFormatProvider provider = new PdfFormatProvider();
provider.ImportSettings.ReadingMode = ReadingMode.OnDemand;
RadFixedDocument document = provider.Import(File.ReadAllBytes("SampleDoc.pdf"), TimeSpan.FromSeconds(10));
document.DocumentUnhandledException += (s, e) =>
{
    Debug.WriteLine("The document is corrupted and cannot be loaded: " + e.Exception.Message);
    e.Handled = true;
};
```

## Using ExportSettings.DocumentUnhandledException

Starting with **Q1 2025**, the [PdfExportSettings](https://www.telerik.com/document-processing-libraries/documentation/libraries/radpdfprocessing/formats-and-conversion/pdf/pdfformatprovider/settings#export-settings) offers the `DocumentUnhandledException` event that allows you to handle exceptions while exporting a document.

**Using the DocumentUnhandledException Event While Exporting**

```C#
PdfFormatProvider provider = new PdfFormatProvider();
PdfExportSettings settings = new PdfExportSettings();
provider.ExportSettings.DocumentUnhandledException += (s, e) =>
{
    Debug.WriteLine("The document is corrupted and cannot be exported: " + e.Exception.Message);
    e.Handled = true;
};
```

## Exceptions

| Exception                                      | Description                                                                                                                                                                                                                                          |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DuplicatedEmbeddedFileNameException`          | Represents an exception for embedding a file with a duplicated name.                                                                                                                                                                                 |
| `InvalidActionException`                       | Represents an exception for importing an invalid action.                                                                                                                                                                                             |
| `InvalidGraphicOperandsCountException`         | Represents an exception for importing a graphic operator with an invalid number of operands.                                                                                                                                                         |
| `NotSupportedActionException`                  | Represents an exception for an action that is not supported.                                                                                                                                                                                         |
| `NotSupportedCCITTFaxDecodeFilterException`    | Represents an exception for a scan decoder that is not supported.                                                                                                                                                                                    |
| `NotSupportedCharsetFormatException`           | Represents an exception for a charset format that is not supported. This exception has a `CharsetFormat` property that specifies the name of the CharsetFormat.                                                                                      |
| `NotSupportedColorSpaceException`              | Represents an exception for a color space that is not supported. This exception has a `ColorSpace` property that specifies the name of the ColorSpace.                                                                                               |
| `NotSupportedCompressionMethodException`       | Represents an exception for importing a FlateDecode method that is not supported.                                                                                                                                                                    |
| `NotSupportedEncryptionException`              | Represents an exception for an encryption that is not supported. This exception has an `EncryptionCode` property that specifies the code of the encryption.                                                                                          |
| `NotSupportedEncryptionRevisionException`      | Represents an exception for an encryption revision that is not supported. This exception has a `RevisionCode` property that specifies the name of the RevisionCode.                                                                                  |
| `NotSupportedFeatureException`                 | Represents an exception for a feature that is not supported.                                                                                                                                                                                         |
| `NotSupportedFilterException`                  | Represents an exception for a filter that is not supported. This exception has a `FilterName` property that specifies the name of the filter.                                                                                                        |
| `NotSupportedFontException`                    | Represents an exception for a font that is not supported. This exception has a `FontType` property that specifies the type of the font.                                                                                                              |
| `NotSupportedFontFamilyException`              | Represents an exception for a font family that is not supported.                                                                                                                                                                                     |
| `NotSupportedFunctionTypeException`            | Represents an exception for a function type that is not supported. This exception has a `FunctionType` property that specifies the name of the FunctionType.                                                                                         |
| `NotSupportedPaintTypeException`               | Represents an exception for a paint type that is not supported. This exception has a `PaintType` property that specifies the name of the PaintType.                                                                                                  |
| `NotSupportedPredefinedCMapException`          | Represents an exception for a predefined CMap that is not supported. This exception has a `CMapName` property that specifies the name of the predefined CMap.                                                                                        |
| `NotSupportedReservedMethodException`          | Represents an exception for importing a FlateDecode reserved method that is not supported.                                                                                                                                                           |
| `NotSupportedScanDecoderException`             | Represents an exception for a document with a scan decoder that is not supported.                                                                                                                                                                    |
| `NotSupportedScanEncoderException`             | Represents an exception for a scan decoder that is not supported.                                                                                                                                                                                    |
| `NotSupportedShadingTypeException`             | Represents an exception for a shading type that is not supported. This exception has a `ShadingType` property that specifies the type of the shading.                                                                                                |
| `NotSupportedStreamTypeException`              | Represents an exception for a stream type that is not supported. A stream is not supported if it does not support read or seek. This exception has `SupportSeek` and `SupportRead` properties that specify whether the stream supports them.         |
| `NotSupportedXObjectTypeException`             | Represents an exception for a document with an XObject type that is not supported.                                                                                                                                                                   |
| `DuplicatedJavaScriptNameException`            | Represents an exception for JavaScript with a duplicated name.                                                                                                                                                                                       |
| `NotSupportedImageFormatException`             | Represents an exception thrown when attempting to use an image format that is not supported by the library.                                                                                                                                          |
| `JpxImageDecoderNotConfiguredException`        | Represents an exception thrown when JPX image processing requires a decoder that is not registered through `FixedExtensibilityManager.JpxImageDecoder`. You can handle it through `DocumentUnhandledException` to skip the JPX image content.        |
| `InvalidAnnotationException`                   | Represents an exception for an annotation that is not valid.                                                                                                                                                                                         |
| `NotSupportedAnnotationException`              | Represents an exception for an annotation that is not supported.                                                                                                                                                                                     |
| `InvalidImageDataException`                    | Represents an exception for importing invalid image data.                                                                                                                                                                                            |
| `NotSupportedPdfPrimitivesConversionException` | Represents an exception thrown when attempting to convert unsupported PDF primitive types.                                                                                                                                                           |
| `InvalidStructureTreeException`                | Reports malformed structure-tree entries during import, such as invalid page, object, or marked-content references. `PdfImportSettings.InvalidStructureTreeHandling` and the event handler control whether import throws the exception or continues. |
| `InvalidObjectReferenceException`              | Thrown when a PDF object reference is invalid during import or processing. This occurs when a structure element object reference points to an unrecognized object type.                                                                              |
| `InvalidPageReferenceException`                | Thrown when a PDF page reference is invalid during import or processing. This occurs when a structure element Page property references a non-page object.                                                                                            |

## See Also

* [RadPdfProcessing Overview](https://www.telerik.com/document-processing-libraries/documentation/libraries/radpdfprocessing/overview)
* [PDF import and export settings](https://www.telerik.com/document-processing-libraries/documentation/libraries/radpdfprocessing/formats-and-conversion/pdf/pdfformatprovider/settings)
* [SkiaImageExportSettings](https://www.telerik.com/document-processing-libraries/documentation/libraries/radpdfprocessing/formats-and-conversion/convert-to-image/settings)
