Diagnostics

The editor reports diagnostics for document opening, editing, review, fonts, and collaboration. Failure diagnostics carry stable codes. Look up a code to get a fixed hint with its cause and recommended action.

Diagnostics never contain document content. The editor builds them from closed lists of codes, booleans, and bucketed numbers. Document text, part names, relationship targets, author names, and font names are never included. You can export these fields to an error tracker or metrics backend. Review any attributes that you add and any data your SDK collects. For more information, see Privacy review checklist.

Receive diagnostics

Register a module with an onDiagnostic listener to receive diagnostics from the initial document open. The editor opens that document before your code can call editor.on.

import { DocxEditor } from '@docx-editor.dev/react';
import { explainDiagnostic, type EditorDiagnostic, type EditorModule } from '@docx-editor.dev/core';

// Create the module once, outside the component. The editor reads modules only at creation.
const diagnostics: EditorModule = {
  id: 'diagnostics',
  onDiagnostic: (event: EditorDiagnostic) => {
    if (event.kind === 'edit.rejected') {
      console.warn(event.code, explainDiagnostic(event.code).hint);
    }
  },
};

const MODULES = [diagnostics];

export function Editor({ bytes }: { bytes: Uint8Array }) {
  return <DocxEditor document={bytes} modules={MODULES} />;
}

After the editor exists, you can also subscribe with editor.on('diagnostic', listener). Both receive the same events. A listener that throws doesn't affect the editor.

Diagnostic kinds

Switch on kind to narrow the event. Every event also has schemaVersion, editorSessionId, and time. Each editor instance generates a random editorSessionId and does not persist it. Use it to connect diagnostics from the same instance.

Document sizes and counts use buckets, such as 4-8MiB or 10-99. Rare combinations can still distinguish documents within an organization. The telemetry package omits detailed shape buckets by default.

Failure detail

A code identifies the failure. Optional detail fields identify the engine condition and where it occurred. These fields use closed lists and help you investigate without document content.

Use code for application logic. Use cause for investigation, because these internal reasons can change between versions. To list every cause, call diagnosticCauses().

An open that throws reports open.failed with cause: 'exception', and a command, a review card action, or an editing API batch that throws reports edit.internal-invariant with cause: 'exception'. The error still reaches your code as before. An exception from your own code inside run() is not reported.

These examples show a malformed header and a skipped formatting change:

{ "kind": "document.open", "outcome": "rejected", "code": "open.xml-malformed",
  "cause": "undeclared-prefix", "part": "header", "sizeBucket": "64-128KiB" }

{ "kind": "review.skipped", "code": "review.revision-unsupported", "count": 3,
  "operation": "accept", "changeKind": "format", "formattingKind": "tblGridChange",
  "part": "main-document" }

When you report a problem, include the code, the failure detail, and the engineVersion that your telemetry adds. A refusal's cause names the engine condition that refused it. An exception's errorName and stage say what kind of error it was and where it was caught; they do not include a stack trace.

Codes

Codes are stable. New codes can be added, but existing codes are never renamed. To get the hint for a code in your own code, call explainDiagnostic(code). To get the code for the local refusal message in snapshot().lastRejection, call diagnosticCodeOfRefusal(reason).

Open

Edit

Review

Font

History

Custom nodes

Performance

A performance event summarizes how fast the editor responded during a window. It carries a code only when the summary needs attention.

Collaboration

A collaboration code is collab. followed by the session's own failure code. It appears on collab.status events. An edit that a session refuses is an edit.rejected event with an edit.collaboration-* code instead, so the collab.collaboration-session-* and collab.collaboration-text-limit codes appear only when a session reports them as its status reason.