withastro/astro · error · AstroError

NoMatchingRenderer

NoMatchingRenderer

Error message

Unable to render `${componentName}`.

There ${plural ? 'are' : 'is'} ${validRenderersCount} renderer${plural ? 's' : ''} configured in your `astro.config.mjs` file,
but ${plural ? 'none were' : 'it was not'} able to server-side render `${componentName}`.

What it means

The component is `client:only="<name>"`, the hint matched a known client-only value (so the user gave a real framework name), but none of the configured renderers claim that framework. Astro throws `NoMatchingRenderer`: it knows which framework you intended but the matching integration isn't installed/enabled. The hint suggests probable renderer package names.

Source

Thrown at packages/astro/src/runtime/server/render/component.ts:204

		if (!renderer && metadata.hydrateArgs) {
			const rendererName = metadata.hydrateArgs;
			if (typeof rendererName === 'string') {
				renderer = renderers.find(({ name }) => name === rendererName);
			}
		}
	}

	let componentServerRenderEndTime;
	// If no one claimed the renderer
	if (!renderer) {
		if (metadata.hydrate === 'only') {
			const rendererName = rendererAliases.has(metadata.hydrateArgs)
				? rendererAliases.get(metadata.hydrateArgs)
				: metadata.hydrateArgs;
			if (clientOnlyValues.has(rendererName)) {
				// throw an error if provide correct client:only directive but not find the renderer
				const plural = validRenderers.length > 1;
				throw new AstroError({
					...AstroErrorData.NoMatchingRenderer,
					message: AstroErrorData.NoMatchingRenderer.message(
						metadata.displayName,
						metadata?.componentUrl?.split('.').pop(),
						plural,
						validRenderers.length,
					),
					hint: AstroErrorData.NoMatchingRenderer.hint(
						formatList(probableRendererNames.map((r) => '`' + r + '`')),
					),
				});
			} else {
				// throw an error if an invalid hydration directive was provided
				throw new AstroError({
					...AstroErrorData.NoClientOnlyHint,
					message: AstroErrorData.NoClientOnlyHint.message(metadata.displayName),
					hint: AstroErrorData.NoClientOnlyHint.hint(
						probableRendererNames.map((r) => r.replace('@astrojs/', '')).join('|'),

View on GitHub (pinned to d081033d5f)

Solutions

1. Install and register the matching framework integration (`astro add react`, or add `@astrojs/vue` to `integrations` in config).
2. Verify the renderer appears in your `astro.config` integrations list.
3. Rebuild after adding the integration.

Example fix

// before — client:only="vue" but @astrojs/vue not configured
<VueCounter client:only="vue" />

// after — add the integration
import vue from '@astrojs/vue';
export default defineConfig({ integrations: [vue()] });

// Verify a renderer is registered for the client:only hint before relying on it
function assertRendererInstalled(renderers: string[], hint: string): void {
  const want = `@astrojs/${hint}`;
  if (!renderers.some((r) => r === want || r === hint)) {
    throw new Error(`No renderer configured for client:only="${hint}". Install ${want}.`);
  }
}

const hasRendererFor = (renderers: string[], hint: string): boolean =>
  renderers.some((r) => r === `@astrojs/${hint}` || r === hint);

When it happens

Trigger: `client:only="vue"` without `@astrojs/vue` added to `astro.config`; `client:only="svelte"` with the Svelte integration not installed; the renderer integration is installed but not registered in `astro.config.mjs`.

Common situations: New project that hasn't yet added the framework integration; integration removed/disabled; SSR adapter present but framework integration missing.

Related errors

• NoClientOnlyHint
• You tried to add the ${name} client renderer, but its server
• ${packageName} doesn't appear to be an integration or an ada
• The renderer you passed isn't valid. A renderer is usually a
• The renderer name must be provided when adding a server rend

AI-assisted analysis of withastro/astro@d081033d5f (2026-08-12). Data as JSON: /api/errors/89c1b562313a7971. Report an issue: GitHub.