withastro/astro · error · Error

The renderer name must be provided when adding a server…

Error message

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

What it means

`addServerRenderer` registers a renderer in the container's manifest under a name. If the renderer object is not 'named' (has no `name` property of its own) and no `name` was supplied in the options object, there is nothing to key the renderer by — client renderers are later matched by this exact name — so the call is rejected.

Solutions

Pass the name explicitly: `addServerRenderer({ name: '@astrojs/react', renderer })`
Or give the renderer object itself a `name` property (named renderers are detected automatically)
Use the package name as the name — `addClientRenderer` later matches the server renderer by that same name

Example fix

// before
container.addServerRenderer({ renderer: { check, renderToStaticMarkup } });

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

Defensive patterns

Strategy: type-guard

Type guard

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

const options = { renderer };
if (!rendererHasName(renderer, options)) {
  options.name = 'my-renderer'; // supply the missing name
}
container.addServerRenderer(options);

Prevention

Always pass `name` explicitly in test helpers — conventionally the integration's package name
Keep the name consistent with what `addClientRenderer` will use, since client registration looks the server renderer up by name
When cloning or wrapping a renderer object, carry the `name` property over

When it happens

Trigger: `addServerRenderer({ renderer })` where the renderer object lacks a `name` field — typical for anonymous/custom server renderers built inline in test setup; destructuring or cloning a renderer without carrying `name` over.

Common situations: Custom renderers in container tests; integrations exporting anonymous renderer objects; refactors that wrap a renderer in a new object and drop the `name` property.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

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

Appendix: source

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

		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.#manifest.renderers.push({
				name: renderer.name,
				ssr: renderer,
			});
		} else if ('name' in options) {
			this.#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 3578d45d34)