{"record":{"id":"89c1b562313a7971","repo":"withastro/astro","slug":"nomatchingrenderer","errorCode":"NoMatchingRenderer","errorMessage":"Unable to render `${componentName}`.\n\nThere are ${validRenderersCount} renderers configured in your `astro.config.mjs` file,\nbut none were able to server-side render `${componentName}`.","messagePattern":"Unable to render `(.+?)`\\.\n\nThere are (.+?) renderers configured in your `astro\\.config\\.mjs` file,\nbut none were able to server-side render `(.+?)`\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/runtime/server/render/component.ts","lineNumber":204,"sourceCode":"\t\tif (!renderer && metadata.hydrateArgs) {\n\t\t\tconst rendererName = metadata.hydrateArgs;\n\t\t\tif (typeof rendererName === 'string') {\n\t\t\t\trenderer = renderers.find(({ name }) => name === rendererName);\n\t\t\t}\n\t\t}\n\t}\n\n\tlet componentServerRenderEndTime;\n\t// If no one claimed the renderer\n\tif (!renderer) {\n\t\tif (metadata.hydrate === 'only') {\n\t\t\tconst rendererName = rendererAliases.has(metadata.hydrateArgs)\n\t\t\t\t? rendererAliases.get(metadata.hydrateArgs)\n\t\t\t\t: metadata.hydrateArgs;\n\t\t\tif (clientOnlyValues.has(rendererName)) {\n\t\t\t\t// throw an error if provide correct client:only directive but not find the renderer\n\t\t\t\tconst plural = validRenderers.length > 1;\n\t\t\t\tthrow new AstroError({\n\t\t\t\t\t...AstroErrorData.NoMatchingRenderer,\n\t\t\t\t\tmessage: AstroErrorData.NoMatchingRenderer.message(\n\t\t\t\t\t\tmetadata.displayName,\n\t\t\t\t\t\tmetadata?.componentUrl?.split('.').pop(),\n\t\t\t\t\t\tplural,\n\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 {\n\t\t\t\t// throw an error if an invalid hydration directive was provided\n\t\t\t\tthrow new AstroError({\n\t\t\t\t\t...AstroErrorData.NoClientOnlyHint,\n\t\t\t\t\tmessage: AstroErrorData.NoClientOnlyHint.message(metadata.displayName),\n\t\t\t\t\thint: AstroErrorData.NoClientOnlyHint.hint(\n\t\t\t\t\t\tprobableRendererNames.map((r) => r.replace('@astrojs/', '')).join('|'),","sourceCodeStart":186,"sourceCodeEnd":222,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/src/runtime/server/render/component.ts#L186-L222","documentation":"With client:only=\"react|preact|vue|svelte|solid(-js)\" the hint string is recognized (rendererAliases maps solid to solid-js), but no configured renderer matches it: none of the integrations in astro.config can hydrate that framework, so NoMatchingRenderer is thrown stating how many renderers are configured and hinting at the probable ones. The renderer must be installed and registered even for client:only components.","triggerScenarios":"client:only=\"preact\" while only @astrojs/react is in integrations; client:only=\"solid\" without @astrojs/solid; the framework package was npm-installed but the Astro integration was never added to astro.config; integrations array assembled conditionally and the branch omitted the renderer.","commonSituations":"Copy-pasting components between projects with different integrations; manually installing framework deps instead of running astro add; config refactors that dropped an integration; monorepos sharing a config template.","solutions":["Run npx astro add <framework> (e.g. npx astro add preact) to install and register the matching integration","Verify the integrations array in astro.config.mjs actually includes the renderer for the hinted framework","Restart the dev server after config changes","Alternatively change the hint to a framework you already have installed, if the component supports it"],"exampleFix":"// before: astro.config.mjs\nintegrations: [react()]\n// component uses client:only=\"preact\"\n\n// after\nimport preact from '@astrojs/preact';\nintegrations: [react(), preact()]","handlingStrategy":"validation","validationCode":"// CI check: every client:only hint must have a matching integration\nconst hints = ['react', 'preact', 'vue', 'svelte', 'solid-js']; // values used in templates\nconst installed = config.integrations.map((i) => i.name);\nfor (const h of hints) {\n  if (!installed.some((n) => n.includes(h.replace('-js', '')))) {\n    throw new Error('client:only=\"' + h + '\" used but its renderer is not in astro.config');\n  }\n}","typeGuard":"function hasRendererFor(config: { integrations: { name: string }[] }, framework: string): boolean {\n  return config.integrations.some((i) => i.name.includes(framework));\n}","tryCatchPattern":null,"preventionTips":["Add integrations with npx astro add instead of manual installs","Keep the astro.config integrations list in sync with every client:only hint used in templates","Restart the dev server after changing integrations"],"tags":["astro","client-only","renderer","integration","hydration"],"backgroundTag":"missing-framework-renderer","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}