mozilla/pdf.js · error · FormatError

GState must be referred to by name.

Error message

GState must be referred to by name.

What it means

FormatError thrown while processing the setGState operator when its operand is not a PDF Name. setGState (the 'gs' operator) must take a name that keys into the ExtGState resource dictionary; a non-Name operand is malformed.

Source

Thrown at src/core/evaluator.js:2177

          case OPS.setGState:
            isValidName = args[0] instanceof Name;
            name = args[0].name;

            if (isValidName) {
              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,

View on GitHub (pinned to 5903d58d58)

Solutions

1. Enable ignoreErrors: true so the malformed gs is skipped.
2. Repair the content stream to pass a proper /Name operand to gs.
3. Upgrade PDF.js.

Example fix

// before
getDocument({ data }); // setGState with non-Name aborts

// after
getDocument({ data, ignoreErrors: true }); // malformed gs skipped

try {
  await page.render({ canvasContext, viewport }).promise;
} catch (e) {
  if (/GState must be referred to by name/.test(e.message)) {
    await reloadWith({ ignoreErrors: true });
  } else throw e;
}

When it happens

Trigger: A content stream emits 'gs' with a non-Name argument (number/string/null), isValidName is false, and the inner promise throws. The setGState handler's .catch honors ignoreErrors.

Common situations: Corrupt content streams, hand-edited PDFs, or buggy generators emitting wrong operand types for gs.

Related errors

• ExtGState should be a dictionary.
• 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/2145638e24c17151. Report an issue: GitHub.