{"record":{"id":"b7694edd896093dd","repo":"squidfunk/mkdocs-material","slug":"missing-element-expected-selector-to-be-pres","errorCode":null,"errorMessage":"Missing element: expected \"${selector}\" to be present","messagePattern":"Missing element: expected \"(.+?)\" to be present","errorType":"exception","errorClass":"ReferenceError","httpStatus":null,"severity":"error","filePath":"src/templates/assets/javascripts/browser/element/_/index.ts","lineNumber":77,"sourceCode":" * @param selector - Query selector\n * @param node - Node of reference\n *\n * @returns Element\n */\nexport function getElement<T extends keyof HTMLElementTagNameMap>(\n  selector: T, node?: ParentNode\n): HTMLElementTagNameMap[T]\n\nexport function getElement<T extends HTMLElement>(\n  selector: string, node?: ParentNode\n): T\n\nexport function getElement<T extends HTMLElement>(\n  selector: string, node: ParentNode = document\n): T {\n  const el = getOptionalElement<T>(selector, node)\n  if (typeof el === \"undefined\")\n    throw new ReferenceError(\n      `Missing element: expected \"${selector}\" to be present`\n    )\n\n  /* Return element */\n  return el\n}\n\n/* ------------------------------------------------------------------------- */\n\n/**\n * Retrieve an optional element matching the query selector\n *\n * @template T - Element type\n *\n * @param selector - Query selector\n * @param node - Node of reference\n *\n * @returns Element or nothing","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/templates/assets/javascripts/browser/element/_/index.ts#L59-L95","documentation":"getElement() is the strict DOM lookup helper in Material for MkDocs' theme JavaScript. It wraps getOptionalElement() and throws a ReferenceError when the selector matches nothing in the document (or the given scope node). The library throws it because the caller requires the element to exist for the page to function, so failing fast is preferable to a silent null dereference later.","triggerScenarios":"Calling getElement<T>(selector) — directly or via getComponentElement, script, target, or inner — with a selector that matches no element, e.g. document.querySelector returns undefined because the element was removed, renamed, or never rendered.","commonSituations":"Custom overrides/patches reference theme internals whose markup changed between Material versions; a hook (like instant loading or tabs) runs before the element is rendered; a typo in a component selector like [data-md-component=...]; running scripts against a partial DOM (e.g. during header construction).","solutions":["Verify the selector exists in the current theme version's DOM; use document.querySelector in the console to check.","If the element is truly optional, switch to getOptionalElement() and handle undefined.","Pin the Material for MkDocs version to match the markup your script targets, and update selectors after upgrades.","Delay the lookup until DOMContentLoaded / after the relevant component mounts, or pass the correct parent node as the second argument."],"exampleFix":"// before\nconst content = getElement(\".md-content__inner\")\n\n// after\nconst content = getOptionalElement(\".md-content__inner\")\nif (typeof content === \"undefined\") return","handlingStrategy":"type-guard","validationCode":"if (document.querySelector(selector) === null) {\n  console.warn(`Element ${selector} not present; skipping setup`)\n  return\n}","typeGuard":"function hasElement<T extends HTMLElement>(selector: string, node: ParentNode = document): node is ParentNode & { querySelector(s: string): T } {\n  return typeof node.querySelector<T>(selector) !== \"undefined\"\n}","tryCatchPattern":"try {\n  const el = getElement<T>(selector)\n  // use el\n} catch (e) {\n  if (e instanceof ReferenceError && e.message.startsWith(\"Missing element\")) {\n    // fall back or bail out gracefully\n  } else throw e\n}","preventionTips":["Prefer getOptionalElement when the element is not guaranteed.","Check the theme's current markup after every Material for MkDocs upgrade.","Run lookups after DOMContentLoaded or the relevant component lifecycle hook.","Test custom scripts on a real built page, not a hand-written HTML stub."],"tags":["javascript","dom","reference-error","missing-element"],"backgroundTag":"missing-dom-element","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}