{"record":{"id":"4864c9ecb864ab66","repo":"mozilla/pdf.js","slug":"the-annotationeditor-is-not-enabled","errorCode":null,"errorMessage":"The AnnotationEditor is not enabled.","messagePattern":"The AnnotationEditor is not enabled\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"web/pdf_viewer.js","lineNumber":2711,"sourceCode":"   *   keyboard action.\n   * @property {boolean} [mustEnterInEditMode] - True if the editor must enter\n   *   edit mode.\n   * @property {boolean} [editComment] - True if the editor must enter\n   *   comment edit mode.\n   */\n\n  /**\n   * @param {AnnotationEditorModeOptions} options\n   */\n  set annotationEditorMode({\n    mode,\n    editId = null,\n    isFromKeyboard = false,\n    mustEnterInEditMode = false,\n    editComment = false,\n  }) {\n    if (!this.#annotationEditorUIManager) {\n      throw new Error(`The AnnotationEditor is not enabled.`);\n    }\n    if (this.#annotationEditorMode === mode) {\n      return; // The AnnotationEditor mode didn't change.\n    }\n    if (!isValidAnnotationEditorMode(mode)) {\n      throw new Error(`Invalid AnnotationEditor mode: ${mode}`);\n    }\n    if (!this.pdfDocument) {\n      return;\n    }\n    this.#preloadEditingData(mode);\n\n    const { eventBus, pdfDocument } = this;\n    const updater = async () => {\n      this.#cleanupSwitchAnnotationEditorMode();\n      this.#annotationEditorMode = mode;\n      await this.#annotationEditorUIManager.updateMode(\n        mode,","sourceCodeStart":2693,"sourceCodeEnd":2729,"githubUrl":"https://github.com/mozilla/pdf.js/blob/5903d58d58e4dd9ce6ffa3834aea8480f06b4ada/web/pdf_viewer.js#L2693-L2729","documentation":"Setting `PDFViewer.annotationEditorMode` requires the annotation editor subsystem to have been initialized at construction. The guard checks `#annotationEditorUIManager`, which is only created when the viewer was built with annotation-editor support enabled (an `enableAnnotationEditor` option other than `AnnotationEditorType.DISABLE`, plus the editor layer builder attached). Throwing here prevents callers from driving an editor UI that has no backing manager. It fires before any validation of `mode` itself, so even a benign `mode: AnnotationEditorType.NONE` will trip it if the manager was never created.","triggerScenarios":"Calling `pdfViewer.annotationEditorMode = { mode: ... }` on a viewer instance whose constructor was given `enableAnnotationEditor: false`/omitted, or `DISABLE`. Also when the AnnotationEditorLayerBuilder was never attached to the page viewer, leaving `#annotationEditorUIManager` null.","commonSituations":"Embedding PDF.js in a custom app with a minimal config that omits editor options; upgrading PDF.js versions where the editor feature became opt-in; reading `mode` from a toolbar toggle before the document (and thus editing data) is ready.","solutions":["Construct the viewer with `enableAnnotationEditor` set to a non-DISABLE mode (e.g. `AnnotationEditorType.EDIT_FREETEXT`) if you intend to use editors.","Ensure the AnnotationEditorLayerBuilder is registered for each page view so the UI manager is instantiated.","Gate the assignment: only set `annotationEditorMode` when you know editing is enabled (track the flag you passed at construction).","If editing must be optional, wrap the assignment and degrade gracefully (disable the toolbar control) instead of letting the throw propagate."],"exampleFix":"// before\nconst viewer = new PDFViewer({ container, viewer: div }); // no editor opts\nviewer.annotationEditorMode = { mode: AnnotationEditorType.EDIT_FREETEXT };\n// after\nconst viewer = new PDFViewer({\n  container,\n  viewer: div,\n  enableAnnotationEditor: AnnotationEditorType.EDIT_FREETEXT,\n});\nviewer.annotationEditorMode = { mode: AnnotationEditorType.EDIT_FREETEXT };","handlingStrategy":"validation","validationCode":"// Track the flag you passed at construction; gate the setter.\nconst editorEnabled = enableAnnotationEditor && enableAnnotationEditor !== AnnotationEditorType.DISABLE;\nfunction setEditorMode(viewer, mode) {\n  if (!editorEnabled) {\n    console.warn('Annotation editor not enabled at construction; ignoring mode change.');\n    return;\n  }\n  viewer.annotationEditorMode = { mode };\n}","typeGuard":"// There is no public field exposing #annotationEditorUIManager, so guard via\n// construction state (the only thing that creates the manager).\nfunction viewerSupportsEditors(enableAnnotationEditor) {\n  return (\n    enableAnnotationEditor != null &&\n    enableAnnotationEditor !== -1 /* AnnotationEditorType.DISABLE */\n  );\n}","tryCatchPattern":"try {\n  viewer.annotationEditorMode = { mode };\n} catch (e) {\n  if (/AnnotationEditor is not enabled/.test(e.message)) {\n    disableEditorToolbar(); // graceful degrade\n  } else {\n    throw e;\n  }\n}","preventionTips":["Set enableAnnotationEditor at construction whenever editor UI is reachable.","Keep the editor toolbar control disabled until you confirm the manager exists.","Don't assume a later set of annotationEditorMode can lazily enable editing — it can't."],"tags":["annotation-editor","configuration","api-misuse","pdf-viewer"],"backgroundTag":null,"analyzedSha":"5903d58d58e4dd9ce6ffa3834aea8480f06b4ada","analyzedAt":"2026-08-13T02:28:27.364Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}