{"record":{"id":"f5d6302e399d8ecb","repo":"withastro/astro","slug":"unable-to-render-displayname-this-component-l","errorCode":null,"errorMessage":"Unable to render ${displayName}!\n\nThis component likely uses ${probableRendererNames},\nbut Astro encountered an error during server-side rendering.\n\nPlease ensure that ${displayName}:\n1. Does not unconditionally access browser-specific globals like `window` or `document`.\n   If this is unavoidable, use the `client:only` hydration directive.\n2. Does not conditionally return `null` or `undefined` when rendered on the server.\n3. If using multiple JSX frameworks at the same time (e.g. React + Preact), pass the correct `include`/`exclude` options to integrations.\n\nIf you're still stuck, please open an issue on GitHub or join us at https://astro.build/chat.","messagePattern":"Unable to render \\$\\{displayName\\}!\n\nThis component likely uses \\$\\{probableRendererNames\\},\nbut Astro encountered an error during server-side rendering\\.\n\nPlease ensure that \\$\\{displayName\\}:\n1\\. Does not unconditionally access browser-specific globals like `window` or `document`\\.\n   If this is unavoidable, use the `client:only` hydration directive\\.\n2\\. Does not conditionally return `null` or `undefined` when rendered on the server\\.\n3\\. If using multiple JSX frameworks at the same time \\(e\\.g\\. React \\+ Preact\\), pass the correct `include`/`exclude` options to integrations\\.\n\nIf you're still stuck, please open an issue on GitHub or join us at https://astro\\.build/chat\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/astro/src/runtime/server/render/component.ts","lineNumber":256,"sourceCode":"\t\t\t\t\t\tvalidRenderers.length,\n\t\t\t\t\t),\n\t\t\t\t\thint: AstroErrorData.NoMatchingRenderer.hint(\n\t\t\t\t\t\tformatList(probableRendererNames.map((r) => '`' + r + '`')),\n\t\t\t\t\t),\n\t\t\t\t});\n\t\t\t} else if (matchingRenderers.length === 1) {\n\t\t\t\t// We already know that renderer.ssr.check() has failed\n\t\t\t\t// but this will throw a much more descriptive error!\n\t\t\t\trenderer = matchingRenderers[0];\n\t\t\t\t({ html, attrs } = await renderer.ssr.renderToStaticMarkup.call(\n\t\t\t\t\t{ result },\n\t\t\t\t\tComponent,\n\t\t\t\t\tpropsWithoutTransitionAttributes,\n\t\t\t\t\tchildren,\n\t\t\t\t\tmetadata,\n\t\t\t\t));\n\t\t\t} else {\n\t\t\t\tthrow new Error(`Unable to render ${metadata.displayName}!\n\nThis component likely uses ${formatList(probableRendererNames)},\nbut Astro encountered an error during server-side rendering.\n\nPlease ensure that ${metadata.displayName}:\n1. Does not unconditionally access browser-specific globals like \\`window\\` or \\`document\\`.\n   If this is unavoidable, use the \\`client:only\\` hydration directive.\n2. Does not conditionally return \\`null\\` or \\`undefined\\` when rendered on the server.\n3. If using multiple JSX frameworks at the same time (e.g. React + Preact), pass the correct \\`include\\`/\\`exclude\\` options to integrations.\n\nIf you're still stuck, please open an issue on GitHub or join us at https://astro.build/chat.`);\n\t\t\t}\n\t\t}\n\t} else {\n\t\tif (metadata.hydrate === 'only') {\n\t\t\thtml = await renderSlotToString(result, slots?.fallback);\n\t\t} else {\n\t\t\tconst componentRenderStartTime = performance.now();","sourceCodeStart":238,"sourceCodeEnd":274,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/src/runtime/server/render/component.ts#L238-L274","documentation":"Astro could determine which renderer(s) should handle the component (by extension-derived probable renderer names), but server-side rendering failed or is ambiguous. With exactly one probable renderer it re-runs renderToStaticMarkup to surface that renderer's real error; with several probable renderers (e.g. .jsx with both React and Preact installed) it throws this consolidated guidance message enumerating the classic causes.","triggerScenarios":"Component code touching window, document, or localStorage at module top level or during render on the server; a component whose SSR output is null/undefined in a way the renderer rejects; React and Preact (or multiple JSX renderers) configured simultaneously without include/exclude so neither claims the component cleanly.","commonSituations":"Browser-only libraries (maps, charts, analytics) imported at the top of a component; components that early-return undefined when props are missing during SSR; monorepos or starter templates shipping react + preact together.","solutions":["Guard browser APIs: run them only when !import.meta.env.SSR, or inside useEffect/onMount lifecycle hooks","Ensure the component returns valid markup in every branch (throw on missing props instead of returning undefined)","When multiple JSX renderers are installed, give each integration include/exclude patterns so only one matches the file","As a last resort use client:only=\"<framework>\" so the component renders exclusively in the browser"],"exampleFix":"// before\nimport { initMap } from 'map-lib';\ninitMap(); // crashes during SSR\n\n// after\nimport { initMap } from 'map-lib';\nif (!import.meta.env.SSR) {\n  initMap();\n}","handlingStrategy":"validation","validationCode":"// guard browser-only initialization inside the component\nif (!import.meta.env.SSR) {\n  initBrowserLib();\n}","typeGuard":"function canUseBrowserApis(): boolean {\n  return typeof window !== 'undefined';\n}","tryCatchPattern":null,"preventionTips":["Keep window/document/localStorage access out of module top-level scope; run it in onMount/useEffect or behind !import.meta.env.SSR","Never return undefined from framework components during SSR; throw or render a placeholder instead","Configure include/exclude on each JSX-framework integration when several are installed"],"tags":["astro","ssr","framework-component","browser-globals","renderer"],"backgroundTag":"browser-globals-during-ssr","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}