{"record":{"id":"4c9ef6911fc6dddc","repo":"withastro/astro","slug":"unable-to-render-metadata-displayname-this-co","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","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/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/runtime/server/render/component.ts#L238-L274","documentation":"The ambiguous-multiple-renderers branch: more than one renderer's name matched the component, so Astro picked one and called its `ssr.renderToStaticMarkup`, but the SSR render itself failed (threw or returned no markup). This is a generic catch-all guiding you to the most common SSR failure causes rather than a specific AstroError code.","triggerScenarios":"Component unconditionally reads `window`/`document`/`localStorage` during module evaluation or render; the component conditionally returns `null`/`undefined`; multiple JSX integrations (React + Preact) are active and resolving to the wrong one; the framework component throws internally during SSR.","commonSituations":"Browser-only libraries (charts, maps, editors) imported into an SSR'd component; React/Preact confusion when both are installed; components that render `null` until a client effect runs.","solutions":["Guard browser-global access behind `if (typeof window !== 'undefined')` or an `import.meta.env.SSR` check.","Switch the component to `client:only=\"<framework>\"` if it cannot run on the server at all.","Avoid unconditionally returning `null`/`undefined` during SSR.","When using two JSX frameworks together, configure each integration's `include`/`exclude` so components route to the correct renderer."],"exampleFix":"// before — component reads window at render time\nexport default function Map() {\n  const w = window.innerWidth; // throws during SSR\n  return <canvas width={w} />;\n}\n\n// after — guard, or render client-only\nimport Map from './Map.tsx';\n<Map client:only=\"react\" />","handlingStrategy":"try-catch","validationCode":"// Guard browser globals before they're accessed\nconst isBrowser = typeof window !== 'undefined';\nconst width = isBrowser ? window.innerWidth : 0;","typeGuard":"const canSSR = (Comp: unknown): boolean => {\n  // best-effort: only SSR components that don't need browser globals at import time\n  try { return typeof Comp === 'function'; } catch { return false; }\n};","tryCatchPattern":"// Sandbox SSR of a risky component and fall back to client:only\nlet html: string | null = null;\ntry {\n  html = renderToStringSSR(Risky);\n} catch (e) {\n  // log and skip SSR; render with client:only instead\n}","preventionTips":["Gate all browser-global access behind `import.meta.env.SSR` / `typeof window` checks.","Use `client:only` for components that fundamentally can't SSR.","Configure `include`/`exclude` on JSX integrations when running two frameworks."],"tags":["ssr","browser-globals","framework-components","renderer"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}