What causes "doc.documentFileName is read-only" in mozilla/pdf.js?

Remove the assignment to `doc.documentFileName`; read it through the getter instead.

mozilla/pdf.js · error · Error

doc.documentFileName is read-only

Error message

doc.documentFileName is read-only

What it means

PDF.js's scripting sandbox (src/scripting_api) implements the Acrobat JavaScript `doc` object inside a QuickJS sandbox. Per the Acrobat API specification this property is read-only, so the class defines a getter that returns the current value and a setter that unconditionally throws `Error("doc.<prop> is read-only")`. The throw aborts the currently executing sandboxed script event and is reported back to the host. `documentFileName` is the filename of the open PDF (seeded from `data.filename`); the script cannot rename the open document.

Source

Thrown at src/scripting_api/doc.js:343

  set disclosed(disclosed) {
    this._disclosed = disclosed;
  }

  get docID() {
    return this._docID;
  }

  set docID(_) {
    throw new Error("doc.docID is read-only");
  }

  get documentFileName() {
    return this._documentFileName;
  }

  set documentFileName(_) {
    throw new Error("doc.documentFileName is read-only");
  }

  get dynamicXFAForm() {
    return false;
  }

  set dynamicXFAForm(_) {
    throw new Error("doc.dynamicXFAForm is read-only");
  }

  get external() {
    // According to the specification this should be `true` in non-Acrobat
    // applications, however we ignore that to avoid bothering users with
    // an `alert`-dialog on document load (see issue 15509).
    return DOC_EXTERNAL;
  }

  set external(_) {

View on GitHub (pinned to 5903d58d58)

Solutions

Remove the assignment to `doc.documentFileName`; read it through the getter instead.
Rename the file on disk before opening; pdf.js will then report the new name.
If you cannot edit the PDF's embedded script, wrap the statement in try/catch so the rest of the form logic still runs.

Example fix

// before
doc.documentFileName = "renamed.pdf";
// after
// documentFileName is read-only — drop the assignment; read via doc.documentFileName

Defensive patterns

Strategy: validation

Validate before calling

// Known read-only doc properties (PDF.js scripting_api/doc.js)
const READONLY_DOC_PROPS = new Set([
  'author','bookmarkRoot','creator','dataObjects','docID',
  'documentFileName','dynamicXFAForm','external','filesize','hidden',
  'hostContainer','icons','info','innerAppWindowRect','innerDocWindowRect',
  'isModal','keywords','modDate'
]);
if (READONLY_DOC_PROPS.has('documentFileName')) {
  // skip the write; documentFileName is read-only in pdf.js
  console.warn('doc.documentFileName is read-only in pdf.js');
} else {
  doc.documentFileName = value;
}

Type guard

// Known read-only doc properties (PDF.js scripting_api/doc.js)
const READONLY_DOC_PROPS = new Set([
  'author','bookmarkRoot','creator','dataObjects','docID',
  'documentFileName','dynamicXFAForm','external','filesize','hidden',
  'hostContainer','icons','info','innerAppWindowRect','innerDocWindowRect',
  'isModal','keywords','modDate'
]);
const isReadOnlyDocProp = (name) => READONLY_DOC_PROPS.has(name);
// usage: if (!isReadOnlyDocProp('keywords')) doc.keywords = v;

Try / catch

try {
  doc.documentFileName = value;
} catch (e) {
  // pdf.js throws Error('doc.documentFileName is read-only')
  if (/is read-only/.test(e.message)) { /* swallow, expected */ }
  else { throw e; }
}

Prevention

Treat every property listed in the Acrobat JS reference as read-only unless pdf.js provides a setter that stores the value.
Before assigning, check `isReadOnlyDocProp('documentFileName')` or grep the setter in src/scripting_api/doc.js for a `throw`.
When porting scripts from Acrobat, run them against the pdf.js sandbox in the dev server first to surface writes early.
Prefer reading metadata through the Info dictionary at PDF authoring time rather than mutating it from a script.

When it happens

Trigger: A sandboxed PDF form/script executes an assignment to the property, e.g. `doc.documentFileName = value;` or `doc.documentFileName++`. Because the setter always throws (there is no condition), any write attempt triggers it.

Common situations: Scripts ported from desktop Acrobat where the filename could be set from script; forms that try to stamp runtime state into document metadata on save/open; and PDFs generated by tools that emit non-spec-compliant JavaScript.

Related errors

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