{"record":{"id":"83f1050ac0f57bbd","repo":"mozilla/pdf.js","slug":"invalid-optionalcontentconfigpromise-promise","errorCode":null,"errorMessage":"Invalid optionalContentConfigPromise: ${promise}","messagePattern":"Invalid optionalContentConfigPromise: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"web/pdf_viewer.js","lineNumber":2265,"sourceCode":"    if (!this.pdfDocument) {\n      return Promise.resolve(null);\n    }\n    if (!this._optionalContentConfigPromise) {\n      console.error(\"optionalContentConfigPromise: Not initialized yet.\");\n      // Prevent issues if the getter is accessed *before* the `onePageRendered`\n      // promise has resolved; won't (normally) happen in the default viewer.\n      return this.pdfDocument.getOptionalContentConfig({ intent: \"display\" });\n    }\n    return this._optionalContentConfigPromise;\n  }\n\n  /**\n   * @param {Promise<OptionalContentConfig>} promise - A promise that is\n   *   resolved with an {@link OptionalContentConfig} instance.\n   */\n  set optionalContentConfigPromise(promise) {\n    if (!(promise instanceof Promise)) {\n      throw new Error(`Invalid optionalContentConfigPromise: ${promise}`);\n    }\n    if (!this.pdfDocument) {\n      return;\n    }\n    if (!this._optionalContentConfigPromise) {\n      // Ignore the setter *before* the `onePageRendered` promise has resolved,\n      // since it'll be overwritten anyway; won't happen in the default viewer.\n      return;\n    }\n    this._optionalContentConfigPromise = promise;\n\n    this.refresh(false, { optionalContentConfigPromise: promise });\n\n    this.eventBus.dispatch(\"optionalcontentconfigchanged\", {\n      source: this,\n      promise,\n    });\n  }","sourceCodeStart":2247,"sourceCodeEnd":2283,"githubUrl":"https://github.com/mozilla/pdf.js/blob/5903d58d58e4dd9ce6ffa3834aea8480f06b4ada/web/pdf_viewer.js#L2247-L2283","documentation":"Thrown by PDFViewer.optionalContentConfigPromise setter when the value is not a Promise instance (instanceof Promise check fails). Optional content (OCG/OCMD layers) are refreshed asynchronously and require a promise resolving to an OptionalContentConfig.","triggerScenarios":"Setting viewer.optionalContentConfigPromise = configObject, a plain value, null, or a thenable that is not a native Promise. Also when assigning before the document is loaded (handled by no-op, but type still checked).","commonSituations":"Passing the config directly instead of a promise; using a non-native thenable (some polyfills); forgetting to wrap: Promise.resolve(config).","solutions":["Pass a Promise: viewer.optionalContentConfigPromise = pdfDocument.getOptionalContentConfig({ intent: 'display' }).","Wrap a resolved config: viewer.optionalContentConfigPromise = Promise.resolve(config).","Ensure the value is a real Promise (await/import correctness) before assigning."],"exampleFix":"// before\nviewer.optionalContentConfigPromise = pdfDocument.getOptionalContentConfig({ intent: 'display' });\n// (getOptionalContentConfig returns the config synchronously, not a Promise)\n\n// after\nviewer.optionalContentConfigPromise = Promise.resolve(\n  pdfDocument.getOptionalContentConfig({ intent: 'display' })\n);","handlingStrategy":"type-guard","validationCode":"const config = pdfDocument.getOptionalContentConfig({ intent: 'display' });\nconst promise = (config instanceof Promise) ? config : Promise.resolve(config);\nviewer.optionalContentConfigPromise = promise;","typeGuard":"function isPromise(v) {\n  return v instanceof Promise;\n}","tryCatchPattern":null,"preventionTips":["Always pass a Promise (wrap with Promise.resolve if needed).","Use pdfDocument.getOptionalContentConfig as the source.","Do not assign raw config objects or null."],"tags":["optional-content","layers","validation","promise","setter"],"backgroundTag":null,"analyzedSha":"5903d58d58e4dd9ce6ffa3834aea8480f06b4ada","analyzedAt":"2026-08-13T02:28:27.364Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}