{"record":{"id":"69d8e89223e9a6a5","repo":"withastro/astro","slug":"failed-to-start-the-cloudflare-prerender-server-t","errorCode":null,"errorMessage":"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","messagePattern":"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","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/integrations/cloudflare/src/prerenderer.ts","lineNumber":225,"sourceCode":"\t\t\t\tappType: 'mpa',\n\t\t\t\tbuild: {\n\t\t\t\t\toutDir: fileURLToPath(serverDir),\n\t\t\t\t},\n\t\t\t\troot: fileURLToPath(root),\n\t\t\t\tcustomLogger,\n\t\t\t\tpreview: {\n\t\t\t\t\thost: 'localhost',\n\t\t\t\t\tport: 0, // Let the OS pick a free port\n\t\t\t\t\topen: false,\n\t\t\t\t},\n\t\t\t\tplugins: [cfVitePlugin({ ...cfPluginConfig, viteEnvironment: { name: 'prerender' } })],\n\t\t\t});\n\n\t\t\tconst address = previewServer.httpServer.address();\n\t\t\tif (address && typeof address === 'object') {\n\t\t\t\tserverUrl = `http://localhost:${address.port}`;\n\t\t\t} else {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t'Failed to start the Cloudflare prerender server. The preview server did not return a valid address. ' +\n\t\t\t\t\t\t'This is likely a bug in @astrojs/cloudflare. Please file an issue at https://github.com/withastro/astro/issues',\n\t\t\t\t);\n\t\t\t}\n\t\t},\n\n\t\tasync getStaticPaths(): Promise<PathWithRoute[]> {\n\t\t\t// Call the workerd endpoint to get static paths\n\t\t\tconst response = await fetch(`${serverUrl}${STATIC_PATHS_ENDPOINT}`, {\n\t\t\t\tmethod: 'POST',\n\t\t\t\theaders: { 'Content-Type': 'application/json' },\n\t\t\t});\n\n\t\t\tif (!response.ok) {\n\t\t\t\tconst body = await response.text();\n\t\t\t\tconst details = body ? `\\n${body}` : '';\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Failed to get static paths from the Cloudflare prerender server (${response.status}: ${response.statusText}).${details}`,","sourceCodeStart":207,"sourceCodeEnd":243,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/integrations/cloudflare/src/prerenderer.ts#L207-L243","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Retry the build — transient timing issues with server startup can cause this.","Update `@astrojs/cloudflare` and `astro` to the latest compatible versions; this is treated as an integration bug.","If reproducible, file the issue at https://github.com/withastro/astro/issues with the adapter/Node/Vite versions.","As a workaround, disable the Cloudflare prerender/build-time image features and prerender via a different path."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await build();\n} catch (e) {\n  if (/did not return a valid address/.test(e.message)) {\n    // Retry once; if it persists, report as integration bug.\n  }\n  throw e;\n}","preventionTips":["Keep @astrojs/cloudflare and astro updated to the latest compatible versions.","Retry the build once before investigating — transient startup races can cause this.","Report persistent occurrences with full version info to the astro issue tracker."],"tags":["cloudflare","prerender","internal-bug","server"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}