{"record":{"id":"61eae6a7f6f11d20","repo":"facebook/lexical","slug":"method-is-not-supported-in-headless-mode","errorCode":null,"errorMessage":"${method} is not supported in headless mode","messagePattern":"(.+?) is not supported in headless mode","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/lexical-headless/src/index.ts","lineNumber":36,"sourceCode":"  editorConfig?: CreateEditorArgs,\n): LexicalEditor {\n  const editor = createEditor(editorConfig);\n  editor._headless = true;\n\n  const unsupportedMethods = [\n    'registerDecoratorListener',\n    'registerRootListener',\n    'registerMutationListener',\n    'getRootElement',\n    'setRootElement',\n    'getElementByKey',\n    'focus',\n    'blur',\n  ] as const;\n\n  unsupportedMethods.forEach((method: (typeof unsupportedMethods)[number]) => {\n    editor[method] = () => {\n      throw new Error(`${method} is not supported in headless mode`);\n    };\n  });\n\n  return editor;\n}\n","sourceCodeStart":18,"sourceCodeEnd":42,"githubUrl":"https://github.com/facebook/lexical/blob/76a22dcba981b46119fcec45f935270707e26a57/packages/lexical-headless/src/index.ts#L18-L42","documentation":"createHeadlessEditor wraps a normal Lexical editor but replaces DOM-oriented methods (like focus, blur, and related methods listed in unsupportedMethods) with functions that always throw, because a headless editor has no root element or browser DOM to interact with. Headless editors are for server-side serialization, parsing, and transforms only. Calling any DOM-lifecycle method on one is a programming mistake, so the library fails fast with this message.","triggerScenarios":"Invoking editor.focus(), editor.blur(), or another stubbed DOM method directly on an editor produced by createHeadlessEditor, or calling a library/plugin that internally calls those methods.","commonSituations":"Reusing a headless editor (built for Node/ssr tests) in browser UI code; running shared editor-setup helpers that call focus() after mount against a headless instance; SSR tests importing plugins that auto-focus.","solutions":["Use createEditor (browser) instead of createHeadlessEditor when you need focus/blur behavior","Remove or guard focus()/blur() calls when running in headless/test environments","Use environment detection to skip DOM-only setup code for headless editors"],"exampleFix":"// before\nconst editor = createHeadlessEditor({nodes});\neditor.focus(); // throws: focus is not supported in headless mode\n\n// after\nconst editor = isHeadless ? createHeadlessEditor({nodes}) : createEditor({nodes});\nif (!isHeadless) editor.focus();","handlingStrategy":"try-catch","validationCode":"function supportsDom(editor: LexicalEditor): boolean {\n  return editor._rootElement !== null || !('isHeadless' in editor && editor.isHeadless);\n}\n// only call focus/blur when running a real (non-headless) editor","typeGuard":"function isHeadlessEditor(editor: LexicalEditor): boolean {\n  return (editor as {_headless?: boolean})._headless === true;\n}","tryCatchPattern":"try {\n  editor.focus();\n} catch (e) {\n  if (String(e).includes('not supported in headless mode')) {\n    // expected in headless/test environment; skip DOM behavior\n  } else {\n    throw e;\n  }\n}","preventionTips":["Keep headless editors confined to server/test/serialization code paths","Centralize focus/blur calls in helpers that check the environment first","When sharing setup code, branch on whether the editor has a rootElement"],"tags":["lexical","headless","dom","environment"],"backgroundTag":"unsupported-environment-method","analyzedSha":"76a22dcba981b46119fcec45f935270707e26a57","analyzedAt":"2026-08-31T21:45:54.792Z","schemaVersion":2},"datasetVersion":"2026-08-31T22:30:34.772Z"}