mozilla/pdf.js · error · FormatError

GState should be a dictionary.

Error message

GState should be a dictionary.

What it means

FormatError thrown when a named ExtGState entry itself is not a Dictionary. ExtGState is a Dict, but the specific named value (e.g. 'gs1') resolves to a non-Dict, so the graphics state cannot be interpreted.

Source

Thrown at src/core/evaluator.js:2190

            }

            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,
                    localGStateCache,
                    localColorSpaceCache,
                    seenRefs,
                  })
                  .then(resolveGState, rejectGState);
              }).catch(function (reason) {
                if (reason instanceof AbortException) {
                  return;

View on GitHub (pinned to 5903d58d58)

Solutions

1. Enable ignoreErrors: true so the bad GState entry is skipped.
2. Repair the PDF so the named ExtGState entry is a valid dictionary.
3. Upgrade PDF.js.

Example fix

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

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

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

When it happens

Trigger: extGState.get(name) returns something that is not a Dict (a primitive, stream, or null), so 'gState instanceof Dict' fails.

Common situations: Corrupt individual ExtGState entries, broken indirect refs to a single GState parameter dict, or partially-written PDFs.

Related errors

• GState must be referred to by name.
• ExtGState 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/ee6f6d266891325e. Report an issue: GitHub.