withastro/astro · error · Error

the prerender server responded ${response.status} ${response

Error message

the prerender server responded ${response.status} ${response.statusText}${details}

What it means

Thrown by the Cloudflare prerenderer when the internal prerender HTTP server (a local `workerd` instance fronted by a Vite preview server) returns a non-OK response or an empty body for a page request. The error includes the HTTP status, status text, and a trimmed slice of the response body (first 200 chars) to aid diagnosis. This is the fetch call that renders a single route to capture its HTML.

Source

Thrown at packages/integrations/cloudflare/src/prerenderer.ts:149

	sourcePath: string | undefined,
): Promise<void> {
	const response = await fetch(createImageTransformUrl(serverUrl, originalPath, transform), {
		method: 'POST',
		// Remote images have no local original; the worker fetches those itself.
		...(sourcePath
			? {
					body: Readable.toWeb(createReadStream(sourcePath)) as unknown as BodyInit,
					// Required by Node's fetch whenever the body is a stream.
					duplex: 'half',
				}
			: {}),
	} as RequestInit);

	if (!response.ok || !response.body) {
		// The body can be a full error page, so keep only enough of it to be useful.
		const body = (await response.text().catch(() => '')).replace(/\s+/g, ' ').trim();
		const details = body ? `: ${body.slice(0, 200)}` : '';
		throw new Error(
			`the prerender server responded ${response.status} ${response.statusText}${details}`,
		);
	}

	const outputPath = join(fileURLToPath(clientDir), finalPath);
	await mkdir(dirname(outputPath), { recursive: true });
	// `fetch` types the body as the DOM `ReadableStream`, which is structurally
	// identical to but nominally distinct from the `node:stream/web` one.
	const body = response.body as unknown as NodeReadableStream<Uint8Array>;
	await pipeline(Readable.fromWeb(body), createWriteStream(outputPath));
}

/**
 * Creates a prerenderer that uses Cloudflare's workerd runtime via a preview server.
 * This allows prerendering to happen in the same runtime that will serve the pages.
 */
export function createCloudflarePrerenderer({
	root,

View on GitHub (pinned to d081033d5f)

Solutions

Inspect the trimmed body in the error message — it often contains the workerd stack trace or binding error.
Verify all bindings declared in `wrangler.toml`/`wrangler.jsonc` are present and correctly named for local dev.
Run `astro dev` with the adapter to reproduce the page error with full HMR output before retrying the build.
Check workerd is installed and the version matches what @astrojs/cloudflare expects.

Example fix

// before — binding used but not declared
export const GET = ({ locals }) => Response.json(locals.cfContext.env.MY_KV);

// after — declare binding in wrangler config
// wrangler.jsonc: { "kv_namespaces": [{ "binding": "MY_KV", "id": "..." }] }

Defensive patterns

Strategy: try-catch

Validate before calling

// Before build, smoke-test that all pages render in `astro dev` with the adapter,
// and that every referenced binding is declared in wrangler config.

Try / catch

try {
  await build();
} catch (e) {
  if (/prerender server responded/.test(e.message)) {
    // e.message contains status + trimmed body: inspect for binding/runtime errors
    console.error('Prerender failure:', e.message);
  }
  throw e;
}

Prevention

Declare every binding your pages use in wrangler.toml/wrangler.jsonc.
Run astro dev with the adapter to catch page errors before build.
Keep workerd and @astrojs/cloudflare versions in sync.

When it happens

Trigger: During `astro build` with the Cloudflare adapter in prerender mode, the per-route fetch to the local workerd server returns 4xx/5xx. Causes include an unhandled exception in the page's workerd handler, a missing binding, or workerd crashing. The guard is `!response.ok || !response.body`.

Common situations: A page throws during SSR inside workerd (e.g. referencing an undefined env binding). Missing or misnamed Cloudflare bindings (KV, D1, R2, vars). workerd runtime incompatibility with a dependency. Port conflicts on the ephemeral preview server.

Related errors

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