mozilla/pdf.js · error · Error

XFA: Cannot save new annotations.

Error message

XFA: Cannot save new annotations.

What it means

Plain Error thrown by PDFDocument.saveNewAnnotations when the document is an XFA form. XFA documents are XML-driven and do not store annotations as PDF objects, so the AcroForm/annotation save pipeline cannot operate on them. This is a hard capability gap, not a recoverable condition.

Source

Thrown at src/core/document.js:374

            obj => {
              if (obj instanceof Dict) {
                annotation.oldAnnotation = obj.clone();
              }
            },
            () => {
              warn(`Cannot fetch \`oldAnnotation\` for: ${ref}.`);
            }
          )
        );
        delete annotation.id;
      }
    }
    await Promise.all(promises);
  }

  async saveNewAnnotations(handler, task, annotations, imagePromises, changes) {
    if (this.xfaFactory) {
      throw new Error("XFA: Cannot save new annotations.");
    }
    const partialEvaluator = this.#createPartialEvaluator(handler);

    const deletedAnnotations = new RefMap();
    const existingAnnotations = new RefSet();
    await this.#replaceIdByRef(
      annotations,
      deletedAnnotations,
      existingAnnotations
    );

    const pageDict = this.pageDict;
    const annotationsArray = this.annotations.filter(
      a => !(a instanceof Ref && deletedAnnotations.has(a))
    );
    const newData = await AnnotationFactory.saveNewAnnotations(
      partialEvaluator,
      this.xref,

View on GitHub (pinned to 5903d58d58)

Solutions

  1. Disable annotation editing (and the save button) when pdfDocument.isPureXfa is true.
  2. Convert the XFA PDF to a static AcroForm PDF via Acrobat before allowing annotation edits.
  3. Catch the error and show 'Annotation editing is not supported for XFA documents.'

Example fix

// before
const saveBtn = document.getElementById('save');
saveBtn.disabled = false;

// after
const isXfa = await pdfDocument.getMetadata().then(m => m.info.IsXFA || pdfDocument.isPureXfa);
saveBtn.disabled = !!isXfa;
if (isXfa) showBanner('Annotation editing is unavailable for XFA documents.');
Defensive patterns

Strategy: validation

Validate before calling

const meta = await pdfDocument.getMetadata();
const isXfa = pdfDocument.isPureXfa || meta.info?.IsXFA;
if (isXfa) {
  throw new Error('Annotation editing is not supported for XFA documents.');
}

Type guard

function isXfaDocument(doc) {
  return Boolean(doc?.isPureXfa);
}

Try / catch

try {
  await pdfDocument.saveNewAnnotations(...);
} catch (e) {
  if (e.message === 'XFA: Cannot save new annotations.') {
    notifyUser('Annotation saving is unavailable for XFA documents.');
    return;
  }
  throw e;
}

Prevention

When it happens

Trigger: Calling the annotation-save API (PDFViewerApplication.save or PDFDocumentProxy.saveNewAnnotations under the hood) on a document whose XFA factory is active (i.e., pdfDocument.isPureXfa / has XFA). Triggered when the user adds an annotation and then saves on an XFA document.

Common situations: Viewers that enable annotation editing on all documents without checking the XFA flag; government/enterprise XFA forms; LiveCycle Designer PDFs.

Related errors

AI-assisted analysis of mozilla/pdf.js@5903d58d58 (2026-08-13). Data as JSON: /api/errors/5a8d61409ed20b86. Report an issue: GitHub.