{"record":{"id":"99a272386185b1d8","repo":"mozilla/pdf.js","slug":"must-use-the-same-intent-argument-when-calling-t","errorCode":null,"errorMessage":"Must use the same `intent`-argument when calling the `PDFPageProxy.render` and `PDFDocumentProxy.getOptionalContentConfig` methods.","messagePattern":"Must use the same `intent`-argument when calling the `PDFPageProxy\\.render` and `PDFDocumentProxy\\.getOptionalContentConfig` methods\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/display/api.js","lineNumber":1663,"sourceCode":"      operationsFilter,\n    });\n\n    (intentState.renderTasks ||= new Set()).add(internalRenderTask);\n    const renderTask = internalRenderTask.task;\n\n    Promise.all([\n      intentState.displayReadyCapability.promise,\n      optionalContentConfigPromise,\n    ])\n      .then(([transparency, optionalContentConfig]) => {\n        if (this.destroyed) {\n          complete();\n          return;\n        }\n        this._stats?.time(\"Rendering\");\n\n        if (!(optionalContentConfig.renderingIntent & renderingIntent)) {\n          throw new Error(\n            \"Must use the same `intent`-argument when calling the `PDFPageProxy.render` \" +\n              \"and `PDFDocumentProxy.getOptionalContentConfig` methods.\"\n          );\n        }\n        internalRenderTask.initializeGraphics({\n          transparency,\n          optionalContentConfig,\n        });\n        internalRenderTask.operatorListChanged();\n      })\n      .catch(complete);\n\n    return renderTask;\n  }\n\n  /**\n   * @param {GetOperatorListParameters} params - Page getOperatorList\n   *   parameters.","sourceCodeStart":1645,"sourceCodeEnd":1681,"githubUrl":"https://github.com/mozilla/pdf.js/blob/5903d58d58e4dd9ce6ffa3834aea8480f06b4ada/src/display/api.js#L1645-L1681","documentation":"A generic Error during PDFPageProxy.render: the optionalContentConfig passed in (or the auto-generated one) was built for a renderingIntent whose bitmask does not overlap the current render's renderingIntent. The two must be derived from the same intent (display vs print) so that optional-content (OCG/OCMD) visibility matches. Typically happens when a caller pre-creates getOptionalContentConfig({intent:'display'}) and passes that promise to render({intent:'print'}).","triggerScenarios":"Passing an optionalContentConfigPromise created with intent 'display' to a render call with intent 'print' (or vice versa); mixing a cached optional-content config across display and print renders; reusing a stale promise from a previous render with a different intent.","commonSituations":"Custom viewers that pre-cache OCG state for performance; print workflows that reuse the on-screen OCG config; refactoring that changed the intent string in one place but not the other.","solutions":["Pass the same intent string to both getOptionalContentConfig({intent}) and render({intent}).","Omit optionalContentConfigPromise and let render() auto-generate one matching its own intent.","Create a fresh getOptionalContentConfig promise each time the render intent changes."],"exampleFix":"// before\nconst occ = await doc.getOptionalContentConfig({ intent: 'display' });\nawait page.render({ canvasContext, intent: 'print', optionalContentConfigPromise: Promise.resolve(occ) }).promise; // throws\n\n// after\nconst occPromise = doc.getOptionalContentConfig({ intent: 'print' });\nawait page.render({ canvasContext, intent: 'print', optionalContentConfigPromise: occPromise }).promise;","handlingStrategy":"validation","validationCode":"// Ensure the render intent matches the optional-content config intent.\nfunction renderWithIntent(page, ctx, intent) {\n  const occPromise = page._transport\n    ? page._transport.getOptionalContentConfig(\n        page._transport.getRenderingIntent(intent).renderingIntent\n    )\n    : null;\n  return page.render({ canvasContext: ctx, intent, optionalContentConfigPromise: occPromise });\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pass the same intent string to getOptionalContentConfig and render.","Omit optionalContentConfigPromise to let render auto-generate a matching one.","Do not cache a single OCG promise across display and print renders."],"tags":["api-usage","rendering","optional-content","intent"],"backgroundTag":null,"analyzedSha":"5903d58d58e4dd9ce6ffa3834aea8480f06b4ada","analyzedAt":"2026-08-13T02:28:27.364Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}