withastro/astro · error · Error

Failed to start the Cloudflare prerender server. The…

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

The Cloudflare prerenderer starts a Vite preview server bound to port 0 (OS-assigned) and then reads `previewServer.httpServer.address()` to discover the bound port. If address() does not return an object (null or a pipe/socket path string), the adapter cannot know where to send prerender requests and throws this invariant error, explicitly asking for a bug report. In practice it signals that the HTTP server was not actually listening when queried.

Solutions

Retry the build once — an ephemeral bind race is the most transient cause.
Ensure the astro and @astrojs/cloudflare versions are compatible (update both together).
Try a different Node.js LTS version if on an unusual build.
If reproducible, file an issue at https://github.com/withastro/astro/issues with a minimal reproduction.

Defensive patterns

Strategy: retry

Try / catch

import { build } from 'astro';
async function buildWithRetry(retries = 2) {
  for (let i = 0; i <= retries; i++) {
    try { return await build({ root: './' }); }
    catch (e) {
      const transient = e instanceof Error && e.message.includes('did not return a valid address');
      if (!transient || i === retries) throw e;
    }
  }
}

Prevention

Keep astro and @astrojs/cloudflare on compatible, released versions (update together).
Use a standard Node LTS release for builds.
If it reproduces consistently, capture a minimal repro for the maintainers rather than retrying forever.

When it happens

Trigger: The preview server fails to bind or shuts down between `listen()` and `address()` — exotic Node versions, a server error swallowed before the check, or adapter regressions after upgrades.

Common situations: Rare; typically seen right after upgrading @astrojs/cloudflare or astro to mismatched versions, or in restricted environments where binding even an ephemeral localhost port fails.

Related errors

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

Appendix: source

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

				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 e294953aa8)