withastro/astro · error · Error

Failed to get static paths from the Cloudflare prerender…

Error message

Failed to get static paths from the Cloudflare prerender server (${response.status}: ${response.statusText}).${details}

What it means

After booting the workerd prerender server, the Cloudflare adapter POSTs to an internal endpoint to retrieve the list of routes that should be statically generated. A non-OK response fails the build with this error, appending the workerd response body which carries the root cause. It means route enumeration inside the worker failed, not that any single page failed to render.

Solutions

Read the body appended to the message — it is the stack trace from the workerd process.
Check for route files whose module-level code (imports, side effects) throws under workerd and fix or guard them.
Update @astrojs/cloudflare together with astro; pin wrangler/workerd to a known-good version if a runtime regression is suspected.
Report to https://github.com/withastro/astro/issues if the body shows an internal adapter stack trace.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await build({ root: './' });
} catch (e) {
  const msg = e instanceof Error ? e.message : String(e);
  if (msg.includes('Failed to get static paths')) {
    // the message body contains the workerd stack trace — log it verbatim for triage
    console.error(msg.slice(msg.indexOf('\n')));
    process.exitCode = 1;
  } else throw e;
}

Prevention

Keep route modules side-effect free or workerd-safe at module scope.
Pin adapter and workerd/wrangler to versions tested together in CI.
Exercise a full `astro build` in CI on every PR so route-manifest regressions surface before deploy.

When it happens

Trigger: `astro build` with @astrojs/cloudflare where the worker-side code that walks the route manifest and decides prerenderability throws — for example a broken route module evaluated during startup, an adapter/workers-runtime version mismatch, or malformed route metadata (custom 404 handling, redirects config).

Common situations: Upgrading the adapter or workers runtime and hitting an incompatibility; a route module with top-level code that only fails under workerd; experimental adapter options interacting badly with the routes endpoint.

Related errors

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

Appendix: source

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

			} 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}`,
				);
			}

			const data: StaticPathsResponse = await response.json();

			// Deserialize the routes
			return data.paths.map(({ pathname, route, cacheKey }) => ({
				pathname,
				route: deserializeRouteData(route),
				cacheKey,
			}));
		},

		async render(request, { routeData, collectMetadata }) {
			const body: PrerenderRequest = {
				url: request.url,
				routeData: serializeRouteData(routeData, trailingSlash),

View on GitHub (pinned to e294953aa8)