Handle errors

Document Authoring validates structured fragments before it inserts or loads them. If a fragment is invalid, Document Authoring throws a typed DocAuthError. This can happen when you insert a fragment with insertContentAtCursor() or load a fragment you saved earlier.

Use the DocAuthError type guards to distinguish fragment validation errors from other runtime errors. Then 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 guide.

Understand fragment error types

A DocAuthError is one of three fragment errors. Each error includes a type discriminator and a human-readable message:

• InvalidFragmentTypeError (invalid_fragment_type) — The data isn’t a fragment the SDK recognizes. Its actual field contains the received value.
• UnsupportedFragmentVersionError (unsupported_fragment_version) — The fragment version isn’t supported. The error includes the actual version and the expected version.
• MissingFragmentContentError (missing_fragment_content) — The fragment has no content.

Catch fragment errors

Use isDocAuthError() as a catch-all guard to separate fragment validation failures from other errors. Rethrow errors that you don’t recognize:

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:

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 surface ordinary errors, including file import, document export, and network requests. Handle those operations with a normal try/catch.

Learn more

Refer to these guides for related fragment and document workflows:

• Copy/paste and HTML interoperability — Learn where fragments come from when copying and pasting content.
• Document data and formats — Import, export, and load documents.