{"record":{"id":"a1cbc167fcab83f1","repo":"mozilla/pdf.js","slug":"the-overlay-does-not-exist","errorCode":null,"errorMessage":"The overlay does not exist.","messagePattern":"The overlay does not exist\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"web/overlay_manager.js","lineNumber":54,"sourceCode":"      throw new Error(\"The overlay is already registered.\");\n    }\n    this.#overlays.set(dialog, { canForceClose });\n\n    dialog.addEventListener(\"cancel\", ({ target }) => {\n      if (this.#active === target) {\n        this.#active = null;\n      }\n    });\n  }\n\n  /**\n   * @param {HTMLDialogElement} dialog - The overlay's DOM element.\n   * @returns {Promise} A promise that is resolved when the overlay has been\n   *                    opened.\n   */\n  async open(dialog) {\n    if (!this.#overlays.has(dialog)) {\n      throw new Error(\"The overlay does not exist.\");\n    } else if (this.#active) {\n      if (this.#active === dialog) {\n        throw new Error(\"The overlay is already active.\");\n      } else if (this.#overlays.get(dialog).canForceClose) {\n        await this.close();\n      } else {\n        throw new Error(\"Another overlay is currently active.\");\n      }\n    }\n    this.#active = dialog;\n    dialog.showModal();\n  }\n\n  /**\n   * @param {HTMLDialogElement} dialog - The overlay's DOM element.\n   * @returns {Promise} A promise that is resolved when the overlay has been\n   *                    closed.\n   */","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/mozilla/pdf.js/blob/5903d58d58e4dd9ce6ffa3834aea8480f06b4ada/web/overlay_manager.js#L36-L72","documentation":"Thrown by OverlayManager.open when the dialog passed has never been registered (not in the #overlays WeakMap). open() requires a prior register() call to establish the overlay's metadata and cancel handler.","triggerScenarios":"Calling open(dialog) before register(dialog), or passing a different element reference than the one registered (e.g. re-querying the DOM yields a new node).","commonSituations":"Forgetting to register, registering a stale element reference, or the element being replaced/recreated after registration.","solutions":["Call await OverlayManager.register(dialog) before OverlayManager.open(dialog).","Keep a single cached element reference and reuse it for both register and open.","Avoid re-querying the DOM (querySelector) at open time if the element may have been swapped."],"exampleFix":"// before\nOverlayManager.open(document.getElementById('myDialog'));\n\n// after\nconst dialog = document.getElementById('myDialog');\nawait OverlayManager.register(dialog);\nawait OverlayManager.open(dialog);","handlingStrategy":"validation","validationCode":"const dialog = document.getElementById('myDialog');\nawait OverlayManager.register(dialog); // ensure registered\nawait OverlayManager.open(dialog);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pair open() with a prior register().","Cache the element reference; do not re-query at open time.","Centralize overlay lifecycle in one module."],"tags":["overlay","lifecycle","validation","ui-utils"],"backgroundTag":null,"analyzedSha":"5903d58d58e4dd9ce6ffa3834aea8480f06b4ada","analyzedAt":"2026-08-13T02:28:27.364Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}