{"id":"66b411079c0009c1","repo":"vitest-dev/vitest","slug":"expecting-a-valid-dom-element-but-got-typename","errorCode":null,"errorMessage":"Expecting a valid DOM element, but got ${typeName}.","messagePattern":"Expecting a valid DOM element, but got (.+?)\\.","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"warning","filePath":"packages/browser/src/client/tester/context.ts","lineNumber":567,"sourceCode":"  maxLength: number = Number(defaultOptions?.maxLength ?? import.meta.env.DEBUG_PRINT_LIMIT ?? 7000),\n  prettyFormatOptions: PrettyDOMOptions = {},\n): string {\n  if (maxLength === 0) {\n    return ''\n  }\n\n  if (!dom) {\n    dom = document.body\n  }\n\n  if ('element' in dom && 'all' in dom) {\n    dom = dom.element()\n  }\n\n  const type = typeof dom\n  if (type !== 'object' || !dom.outerHTML) {\n    const typeName = type === 'object' ? dom.constructor.name : type\n    throw new TypeError(`Expecting a valid DOM element, but got ${typeName}.`)\n  }\n\n  const pretty = stringify(dom, Number.POSITIVE_INFINITY, {\n    maxLength,\n    highlight: true,\n    ...defaultOptions,\n    ...prettyFormatOptions,\n  })\n  return dom.outerHTML.length > maxLength\n    ? `${pretty.slice(0, maxLength)}...`\n    : pretty\n}\n\nfunction getElementError(selector: string | Locator, container: Element): Error {\n  const locator = typeof selector === 'string' ? __INTERNAL._asLocator('javascript', selector) : selector.asLocator()\n  const formatted = formatDOM(container)\n  const error = new Error(`Cannot find element with locator: ${locator}\\n\\n${formatted}`)\n  error.name = 'VitestBrowserElementError'","sourceCodeStart":549,"sourceCodeEnd":585,"githubUrl":"https://github.com/vitest-dev/vitest/blob/d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09/packages/browser/src/client/tester/context.ts#L549-L585","documentation":"Thrown by prettyDOM (packages/browser/src/client/tester/context.ts:547-568), which is invoked by page.debug(). After resolving a Locator to its element and defaulting null to document.body, the function checks that the value is an object with an outerHTML property; anything else (number, string, plain object without outerHTML, undefined leaked through) is rejected as a TypeError with the constructor name or typeof result.","triggerScenarios":"Calling page.debug(value) where value is a primitive (string/number), a plain JS object, a NodeList (which has no outerHTML), or an array element passed singularly that isn't a DOM Element/Locator. Also triggered if a Locator.element() returned something unexpected.","commonSituations":"Passing the result of querySelectorAll (a NodeList) instead of a single node; passing an event target that isn't an Element; debugging with console.log-style arguments into page.debug.","solutions":["Pass a single Element or Locator: page.debug(document.querySelector('.x')).","For a NodeList/array, iterate: nodes.forEach(n => page.debug(n)) or use page.debug(Array.from(nodes)) (debug accepts arrays at context.ts:537-540).","Coerce before debugging: page.debug(typeof v === 'string' ? document.body : v)."],"exampleFix":"// before\npage.debug(document.querySelectorAll('.item'))\n// after\npage.debug(Array.from(document.querySelectorAll('.item')))","handlingStrategy":"type-guard","validationCode":"function isDebuggable(v: unknown): v is Element | Locator | (Element | Locator)[] {\n  if (Array.isArray(v)) return v.every(isDebuggable)\n  return v instanceof Element || (v != null && typeof v === 'object' && 'element' in v && 'all' in v)\n}\nif (isDebuggable(maybeNode)) page.debug(maybeNode as any)","typeGuard":"function isDebuggableNode(v: unknown): v is Element | Locator {\n  return v instanceof Element || (v != null && typeof v === 'object' && 'element' in (v as any) && 'all' in (v as any))\n}","tryCatchPattern":null,"preventionTips":["Pass only Element, Locator, or arrays thereof to page.debug.","Convert NodeList via Array.from(...) before debugging."],"tags":["browser","debug","dom","type-error","prettydom"],"analyzedSha":"d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09","analyzedAt":"2026-08-03T20:23:56.861Z","schemaVersion":2}