mozilla/pdf.js · error · FormatError

ExtGState should be a dictionary.

Error message

ExtGState should be a dictionary.

What it means

FormatError thrown when the 'ExtGState' resource entry on the page/stream resources is not a PDF Dictionary. ExtGState must be a name->dictionary map; any other type makes graphics-state lookups impossible.

Source

Thrown at src/core/evaluator.js:2182

              const localGStateObj = localGStateCache.getByName(name);
              if (localGStateObj) {
                if (localGStateObj.length > 0) {
                  operatorList.addOp(OPS.setGState, [localGStateObj]);
                }
                args = null;
                continue;
              }
            }

            next(
              new Promise(function (resolveGState, rejectGState) {
                if (!isValidName) {
                  throw new FormatError("GState must be referred to by name.");
                }

                const extGState = resources.get("ExtGState");
                if (!(extGState instanceof Dict)) {
                  throw new FormatError("ExtGState should be a dictionary.");
                }

                const gState = extGState.get(name);
                // TODO: Attempt to lookup cached GStates by reference as well,
                //       if and only if there are PDF documents where doing so
                //       would significantly improve performance.
                if (!(gState instanceof Dict)) {
                  throw new FormatError("GState should be a dictionary.");
                }

                self
                  .setGState({
                    resources,
                    gState,
                    operatorList,
                    cacheKey: name,
                    task,
                    stateManager,

View on GitHub (pinned to 5903d58d58)

Solutions

1. Enable ignoreErrors: true to skip the bad ExtGState lookup.
2. Repair the PDF so ExtGState is a proper dictionary.
3. Upgrade PDF.js.

Example fix

// before
getDocument({ data }); // non-Dict ExtGState aborts render

// after
getDocument({ data, ignoreErrors: true }); // bad ExtGState skipped

try {
  await page.render({ canvasContext, viewport }).promise;
} catch (e) {
  if (/ExtGState should be a dictionary/.test(e.message)) {
    await reloadWith({ ignoreErrors: true });
  } else throw e;
}

When it happens

Trigger: resources.get('ExtGState') returns something that is not a Dict (null, a stream, a number), so 'extGState instanceof Dict' fails inside the setGState handler.

Common situations: Truncated or malformed resource dictionaries, broken indirect references to the ExtGState sub-dictionary, or generators placing the wrong object type.

Related errors

• GState must be referred to by name.
• GState should be a dictionary.
• Unable to decode inline image: "${reason}".
• Unknown PatternType: ${typeNum}
• Unknown PatternName: ${patternName}

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