---
title: "Error handling"
canonical_url: "https://www.nutrient.io/guides/document-authoring/troubleshooting/error-handling/"
md_url: "https://www.nutrient.io/guides/document-authoring/troubleshooting/error-handling.md"
last_updated: "2026-07-08T00:00:00.000Z"
description: "Handle typed fragment errors in Document Authoring with `DocAuthError` type guards when inserting or loading structured content."
---

# Handle errors

Document Authoring validates structured fragments before it inserts or loads them. For example, when you insert a fragment with [`insertContentAtCursor()`](https://www.nutrient.io/api/document-authoring/types/docautheditor/#insertcontentatcursor) or load a fragment you saved earlier, Document Authoring throws a typed [`DocAuthError`](https://www.nutrient.io/api/document-authoring/types/docautherror/) if the fragment is invalid.

Use the [`DocAuthError`](https://www.nutrient.io/api/document-authoring/types/docautherror/) type guards to distinguish fragment validation errors from other runtime errors and handle each case.

Before you start, make sure the Document Authoring library is installed and running in your app. If you haven’t set it up yet, refer to the [getting started](https://www.nutrient.io/sdk/document-authoring/getting-started.md) guide.

## Understand fragment error types

A [`DocAuthError`](https://www.nutrient.io/api/document-authoring/types/docautherror/) is one of three fragment errors. Each error includes a `type` discriminator and a human-readable `message`:

- [`InvalidFragmentTypeError`](https://www.nutrient.io/api/document-authoring/types/invalidfragmenttypeerror/) (`invalid_fragment_type`) — The data isn’t a fragment the SDK recognizes. Its `actual` field contains the received value.

- [`UnsupportedFragmentVersionError`](https://www.nutrient.io/api/document-authoring/types/unsupportedfragmentversionerror/) (`unsupported_fragment_version`) — The fragment version isn’t supported. The error includes the `actual` version and the `expected` version.

- [`MissingFragmentContentError`](https://www.nutrient.io/api/document-authoring/types/missingfragmentcontenterror/) (`missing_fragment_content`) — The fragment has no content.

## Catch fragment errors

Use [`isDocAuthError()`](https://www.nutrient.io/api/document-authoring/types/docautherror/) as a catch-all guard to separate fragment validation failures from other errors. Rethrow errors that you don’t recognize:

```js

import DocAuth from '@nutrient-sdk/document-authoring';

try {
  editor.insertContentAtCursor({ format: 'fragment', content: fragment });
} catch (error) {
  if (DocAuth.isDocAuthError(error)) {
    console.error(`Fragment rejected: ${error.message}`);
  } else {
    throw error; // Not a Document Authoring error — let it propagate.
  }
}

```

## Handle a specific error

Use the per-type guards to narrow the error and read fields that belong to that error type. This example reports a version mismatch and handles the other fragment error types:

```js

import DocAuth from '@nutrient-sdk/document-authoring';

try {
  editor.insertContentAtCursor({ format: 'fragment', content: fragment });
} catch (error) {
  if (DocAuth.isUnsupportedFragmentVersionError(error)) {
    console.error(`Unsupported fragment version; expected ${error.expected}.`);
  } else if (DocAuth.isInvalidFragmentTypeError(error)) {
    console.error('The data is not a valid fragment.');
  } else if (DocAuth.isMissingFragmentContentError(error)) {
    console.error('The fragment is empty.');
  } else if (DocAuth.isDocAuthError(error)) {
    console.error(error.message);
  } else {
    throw error;
  }
}

```

These typed errors only cover fragment validation. Other operations, such as importing files, exporting documents, or running network requests, surface ordinary errors. Handle those operations with a normal `try`/`catch`.

## Learn more

**[Copy/paste and HTML interoperability](https://www.nutrient.io/guides/document-authoring/editing-content/copy-paste-and-html-interoperability.md)**\
Learn where fragments come from when copying and pasting content.

**[Import and export documents](https://www.nutrient.io/guides/document-authoring/working-with-documents/overview.md)**\
Import, export, and load documents.