{"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":223,"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":205,"sourceCodeEnd":241,"githubUrl":"https://github.com/withastro/astro/blob/e294953aa8aadd98d5be92e60a03037b05dbdfd4/packages/integrations/cloudflare/src/prerenderer.ts#L205-L241","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"import { build } from 'astro';\nasync function buildWithRetry(retries = 2) {\n  for (let i = 0; i <= retries; i++) {\n    try { return await build({ root: './' }); }\n    catch (e) {\n      const transient = e instanceof Error && e.message.includes('did not return a valid address');\n      if (!transient || i === retries) throw e;\n    }\n  }\n}","preventionTips":["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."],"tags":["cloudflare","prerender","internal-invariant","preview-server"],"backgroundTag":"dev-server-startup-failed","analyzedSha":"e294953aa8aadd98d5be92e60a03037b05dbdfd4","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}