{"record":{"id":"2145638e24c17151","repo":"mozilla/pdf.js","slug":"gstate-must-be-referred-to-by-name","errorCode":null,"errorMessage":"GState must be referred to by name.","messagePattern":"GState must be referred to by name\\.","errorType":"exception","errorClass":"FormatError","httpStatus":null,"severity":"error","filePath":"src/core/evaluator.js","lineNumber":2177,"sourceCode":"          case OPS.setGState:\n            isValidName = args[0] instanceof Name;\n            name = args[0].name;\n\n            if (isValidName) {\n              const localGStateObj = localGStateCache.getByName(name);\n              if (localGStateObj) {\n                if (localGStateObj.length > 0) {\n                  operatorList.addOp(OPS.setGState, [localGStateObj]);\n                }\n                args = null;\n                continue;\n              }\n            }\n\n            next(\n              new Promise(function (resolveGState, rejectGState) {\n                if (!isValidName) {\n                  throw new FormatError(\"GState must be referred to by name.\");\n                }\n\n                const extGState = resources.get(\"ExtGState\");\n                if (!(extGState instanceof Dict)) {\n                  throw new FormatError(\"ExtGState should be a dictionary.\");\n                }\n\n                const gState = extGState.get(name);\n                // TODO: Attempt to lookup cached GStates by reference as well,\n                //       if and only if there are PDF documents where doing so\n                //       would significantly improve performance.\n                if (!(gState instanceof Dict)) {\n                  throw new FormatError(\"GState should be a dictionary.\");\n                }\n\n                self\n                  .setGState({\n                    resources,","sourceCodeStart":2159,"sourceCodeEnd":2195,"githubUrl":"https://github.com/mozilla/pdf.js/blob/5903d58d58e4dd9ce6ffa3834aea8480f06b4ada/src/core/evaluator.js#L2159-L2195","documentation":"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.","triggerScenarios":"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.","commonSituations":"Corrupt content streams, hand-edited PDFs, or buggy generators emitting wrong operand types for gs.","solutions":["Enable ignoreErrors: true so the malformed gs is skipped.","Repair the content stream to pass a proper /Name operand to gs.","Upgrade PDF.js."],"exampleFix":"// before\ngetDocument({ data }); // setGState with non-Name aborts\n\n// after\ngetDocument({ data, ignoreErrors: true }); // malformed gs skipped","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await page.render({ canvasContext, viewport }).promise;\n} catch (e) {\n  if (/GState must be referred to by name/.test(e.message)) {\n    await reloadWith({ ignoreErrors: true });\n  } else throw e;\n}","preventionTips":["Enable ignoreErrors for untrusted PDFs.","Repair content streams emitting malformed 'gs' operands.","Upgrade PDF.js."],"tags":["pdf","gstate","graphics-state","malformed-pdf","rendering"],"backgroundTag":null,"analyzedSha":"5903d58d58e4dd9ce6ffa3834aea8480f06b4ada","analyzedAt":"2026-08-13T02:28:27.364Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}