withastro/astro · error · Error

Failed to start the Cloudflare prerender server. The preview

Error message

Failed to start the Cloudflare prerender server. The preview server did not return a valid address. This is likely a bug in @astrojs/cloudflare. Please file an issue at https://github.com/withastro/astro/issues

What it means

Thrown by the Cloudflare prerenderer when, after starting the Vite preview server for prerendering, `previewServer.httpServer.address()` does not return an object with a port. This is an internal invariant failure: the OS should assign a free port (`port: 0`) and return an address object. The message directs users to file a bug.

Source

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

				appType: 'mpa',
				build: {
					outDir: fileURLToPath(serverDir),
				},
				root: fileURLToPath(root),
				customLogger,
				preview: {
					host: 'localhost',
					port: 0, // Let the OS pick a free port
					open: false,
				},
				plugins: [cfVitePlugin({ ...cfPluginConfig, viteEnvironment: { name: 'prerender' } })],
			});

			const address = previewServer.httpServer.address();
			if (address && typeof address === 'object') {
				serverUrl = `http://localhost:${address.port}`;
			} else {
				throw new Error(
					'Failed to start the Cloudflare prerender server. The preview server did not return a valid address. ' +
						'This is likely a bug in @astrojs/cloudflare. Please file an issue at https://github.com/withastro/astro/issues',
				);
			}
		},

		async getStaticPaths(): Promise<PathWithRoute[]> {
			// Call the workerd endpoint to get static paths
			const response = await fetch(`${serverUrl}${STATIC_PATHS_ENDPOINT}`, {
				method: 'POST',
				headers: { 'Content-Type': 'application/json' },
			});

			if (!response.ok) {
				const body = await response.text();
				const details = body ? `\n${body}` : '';
				throw new Error(
					`Failed to get static paths from the Cloudflare prerender server (${response.status}: ${response.statusText}).${details}`,

View on GitHub (pinned to d081033d5f)

Solutions

  1. Retry the build — transient timing issues with server startup can cause this.
  2. Update `@astrojs/cloudflare` and `astro` to the latest compatible versions; this is treated as an integration bug.
  3. If reproducible, file the issue at https://github.com/withastro/astro/issues with the adapter/Node/Vite versions.
  4. As a workaround, disable the Cloudflare prerender/build-time image features and prerender via a different path.
Defensive patterns

Strategy: try-catch

Try / catch

try {
  await build();
} catch (e) {
  if (/did not return a valid address/.test(e.message)) {
    // Retry once; if it persists, report as integration bug.
  }
  throw e;
}

Prevention

When it happens

Trigger: The preview server's underlying `httpServer.address()` returns a string (UNIX socket) or null (closed socket) instead of an `{ port }` object. This happens if the server closed immediately after starting or if the environment does not support TCP address binding as expected.

Common situations: Extremely rare; indicates the preview server failed to bind or closed before the address was read. Can occur in constrained containers, custom server configurations, or after an upstream Vite/Node change in address reporting. Essentially always an integration bug or environment incompatibility, not a user config error.

Related errors

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