{"record":{"id":"563b6ca15e55f58e","repo":"emberjs/ember.js","slug":"you-must-pass-document-or-appendoperations-to-a-ne","errorCode":null,"errorMessage":"you must pass document or appendOperations to a new runtime","messagePattern":"you must pass document or appendOperations to a new runtime","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/@glimmer/runtime/lib/environment.ts","lineNumber":126,"sourceCode":"  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  isArgumentCaptureError: ((error: any) => boolean) | undefined;\n  debugRenderTree: DebugRenderTree<object> | undefined;\n\n  constructor(\n    options: EnvironmentOptions,\n    private delegate: EnvironmentDelegate\n  ) {\n    this.isInteractive = delegate.isInteractive;\n    this.debugRenderTree = this.delegate.enableDebugTooling ? new DebugRenderTree() : undefined;\n    this.isArgumentCaptureError = this.delegate.enableDebugTooling ? isArgumentError : undefined;\n    if (options.appendOperations) {\n      this.appendOperations = options.appendOperations;\n      this.updateOperations = options.updateOperations;\n    } else if (options.document) {\n      this.appendOperations = new DOMTreeConstruction(options.document);\n      this.updateOperations = new DOMChangesImpl(options.document);\n    } else if (DEBUG) {\n      throw new Error('you must pass document or appendOperations to a new runtime');\n    }\n  }\n\n  getAppendOperations(): GlimmerTreeConstruction {\n    return this.appendOperations;\n  }\n\n  getDOM(): GlimmerTreeChanges {\n    return expect(\n      this.updateOperations,\n      'Attempted to get DOM updateOperations, but they were not provided by the environment. You may be attempting to rerender in an environment which does not support rerendering, such as SSR.'\n    );\n  }\n\n  begin() {\n    assert(\n      !this[TRANSACTION],\n      'A glimmer transaction was begun, but one already exists. You may have a nested transaction, possibly caused by an earlier runtime exception while rendering. Please check your console for the stack trace of any prior exceptions.'","sourceCodeStart":108,"sourceCodeEnd":144,"githubUrl":"https://github.com/emberjs/ember.js/blob/26f97246a8bf2e28edf26ac3093da2e86c04ffc5/packages/@glimmer/runtime/lib/environment.ts#L108-L144","documentation":"The Glimmer runtime environment needs DOM operations: either an explicit appendOperations (and updateOperations) pair, or a document from which it can construct DOMTreeConstruction and DOMChangesImpl defaults. If neither is provided, the environment would be unusable, so in DEBUG builds the constructor throws immediately with this message.","triggerScenarios":"new DOMEnvironment()/runtime constructed with an options object that has neither options.document nor options.appendOperations (DEBUG builds only; production silently proceeds with undefined operations).","commonSituations":"Standalone @glimmer/runtime / Glimmer VM setup where the document option was forgotten; wiring a custom environment for SSR (server-side rendering) without supplying custom appendOperations; refactoring runtime boot code and dropping the document option.","solutions":["Pass a document to the runtime options: { document: window.document } (or a DOM implementation like @simple-dom for SSR)","For SSR/custom rendering, pass explicit appendOperations and updateOperations implementations","Check the runtime/environment construction call for a typo'd or undefined options object"],"exampleFix":"// before\nnew RuntimeEnvironment({});\n// after\nnew RuntimeEnvironment({ document: window.document });\n// or for SSR:\nnew RuntimeEnvironment({ appendOperations: new NodeDOMTreeConstruction(doc), updateOperations: new NodeDOMChanges(doc) });","handlingStrategy":"validation","validationCode":"function assertRuntimeOptions(options: { document?: Document; appendOperations?: unknown }) {\n  if (!options?.document && !options?.appendOperations) {\n    throw new Error('runtime requires either `document` or `appendOperations`');\n  }\n}","typeGuard":"interface RuntimeOptions { document?: Document; appendOperations?: unknown; updateOperations?: unknown }\nfunction hasDomTarget(o: RuntimeOptions): boolean {\n  return o.document != null || o.appendOperations != null;\n}","tryCatchPattern":"try {\n  const env = new RuntimeEnvironment(options);\n} catch (e) {\n  if (String(e?.message).includes('document or appendOperations')) {\n    throw new Error('Pass { document } or custom DOM operations when creating the Glimmer runtime');\n  } throw e;\n}","preventionTips":["Always pass a document when constructing the runtime in the browser","For SSR, supply Node-compatible appendOperations/updateOperations explicitly","Keep runtime bootstrapping in one reviewed factory function with options validation","Type runtime options so document/appendOperations are visible required-ish fields"],"tags":["glimmer","configuration","dom","ssr"],"backgroundTag":"missing-required-option","analyzedSha":"26f97246a8bf2e28edf26ac3093da2e86c04ffc5","analyzedAt":"2026-09-01T05:01:28.182Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}