withastro/astro · error · Error

The renderer name must be provided when adding a server rend

Error message

The renderer name must be provided when adding a server renderer that is not a named renderer.

What it means

`addServerRenderer` accepts either a named renderer (an object with its own `name` property) or a `(name, renderer)`/`{name, renderer}` pair. If the renderer is not named AND no `name` was supplied in options, the container cannot register it because the manifest requires a `name` to match against integration/client renderers.

Source

Thrown at packages/astro/src/container/index.ts:391

		const { renderer } = options;
		if (!renderer.check || !renderer.renderToStaticMarkup) {
			throw new Error(
				"The renderer you passed isn't valid. A renderer is usually an object that exposes the `check` and `renderToStaticMarkup` functions.\n" +
					"Usually, the renderer is exported by a /server.js entrypoint e.g. `import renderer from '@astrojs/react/server.js'`",
			);
		}
		if (isNamedRenderer(renderer)) {
			this.#pipeline.manifest.renderers.push({
				name: renderer.name,
				ssr: renderer,
			});
		} else if ('name' in options) {
			this.#pipeline.manifest.renderers.push({
				name: options.name,
				ssr: renderer,
			});
		} else {
			throw new Error(
				'The renderer name must be provided when adding a server renderer that is not a named renderer.',
			);
		}
	}

	/**
	 * Use this function to manually add a **client** renderer to the container.
	 *
	 * When rendering components that use the `client:*` directives, you need to use this function.
	 *
	 * ## Example
	 *
	 * ```js
	 * import reactRenderer from "@astrojs/react/server.js";
	 * import { experimental_AstroContainer as AstroContainer } from "astro/container"
	 *
	 * const container = await AstroContainer.create();
	 * container.addServerRenderer(reactRenderer);

View on GitHub (pinned to d081033d5f)

Solutions

1. Pass an explicit name: `container.addServerRenderer({ name: 'my-renderer', renderer: customRenderer })`.
2. Or give the renderer object a `name` property so `isNamedRenderer` matches.
3. Use the `name` that matches the integration package name so `addClientRenderer` can find it later.

Example fix

// before
container.addServerRenderer({ renderer: customRenderer });
// after
container.addServerRenderer({ name: 'my-renderer', renderer: customRenderer });

const name = renderer.name ?? options.name;
if (!name) throw new Error('Pass a name for unnamed server renderers.');

function hasRendererName(renderer, options): renderer is { name: string } | { name: string } {
  return typeof renderer?.name === 'string' || typeof options?.name === 'string';
}

When it happens

Trigger: Calling `container.addServerRenderer({ renderer: customRenderer })` where `customRenderer` has no `name` property and no `name` option is passed.

Common situations: Writing a custom renderer and forgetting to add a `name`; destructuring only `{ check, renderToStaticMarkup }` from an existing renderer and passing the partial; assuming the container will infer a name from the file path.

Related errors

• The renderer you passed isn't valid. A renderer is usually a
• You tried to add the ${name} client renderer, but its server
• Unable to render ${metadata.displayName}! This component li
• ActionCalledFromServerError
• UNSUPPORTED_MEDIA_TYPE

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