{"record":{"id":"0f509a2229c2d4ba","repo":"sveltejs/kit","slug":"cannot-access-cloudflare-workers-in-a-prerenderabl","errorCode":null,"errorMessage":"Cannot access cloudflare:workers in a prerenderable route","messagePattern":"Cannot access cloudflare:workers in a prerenderable route","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/adapter-cloudflare/src/virtual-cloudflare-workers.js","lineNumber":18,"sourceCode":"import { AsyncLocalStorage } from 'node:async_hooks';\n\nconst als = new AsyncLocalStorage();\n\nconst proxy = globalThis.__sveltekit_cloudflare_platform;\n\nfunction get_current_env() {\n\treturn als.getStore() ?? proxy.env;\n}\n\n/** @typedef {typeof import('@cloudflare/workers-types').CloudflareWorkersModule} Module */\n\nexport const env = new Proxy(\n\t{},\n\t{\n\t\tget(_, prop) {\n\t\t\tif (!proxy) {\n\t\t\t\tthrow new Error(`Cannot access cloudflare:workers in a prerenderable route`);\n\t\t\t}\n\t\t\tconst inner = get_current_env();\n\t\t\tif (inner) {\n\t\t\t\treturn Reflect.get(inner, prop);\n\t\t\t}\n\t\t\treturn undefined;\n\t\t},\n\n\t\tset(_, prop, newValue) {\n\t\t\tif (!proxy) {\n\t\t\t\tthrow new Error(`Cannot access cloudflare:workers in a prerenderable route`);\n\t\t\t}\n\t\t\tconst inner = get_current_env();\n\t\t\tif (inner) {\n\t\t\t\treturn Reflect.set(inner, prop, newValue);\n\t\t\t}\n\t\t\treturn true;\n\t\t},","sourceCodeStart":1,"sourceCodeEnd":36,"githubUrl":"https://github.com/sveltejs/kit/blob/03f1687fe612ce3d2d9131139b5b188d9cf90c64/packages/adapter-cloudflare/src/virtual-cloudflare-workers.js#L1-L36","documentation":"The virtual `cloudflare:workers` module exposes `env` (bindings like KV, D1, R2) only when running as a Cloudflare Worker with a real platform object (`globalThis.__sveltekit_cloudflare_platform`). During prerendering at build time there is no worker runtime, so reading any property of `env` throws. It is a deliberate guard against silently returning undefined bindings for prerendered pages.","triggerScenarios":"Prerendering a route (e.g. `export const prerender = true` or prerender-all config) whose code — including load functions, hooks, or imported modules — evaluates `env.<binding>` from `cloudflare:workers` while `proxy` is null.","commonSituations":"Enabling `prerender` on a page that uses D1/KV bindings; a shared library accessing `env` at module top level gets executed during prerender; SSR fallback code paths run during build prerender.","solutions":["Set `export const prerender = false` for routes that need Cloudflare bindings, or exclude them via `prerender.entries`/handle.","Move `env` access inside request-time code (load functions that only run on the server at request time, API routes) rather than prerendered paths.","Guard access: check `building`/`prerender` context or lazily access `env` only when the binding is actually needed at request time.","Mock `cloudflare:workers` via a Vite alias or `@sveltejs/kit`'s mocking for the prerender/build phase if the value is static."],"exampleFix":"// before (prerendered +settings page)\nimport { env } from 'cloudflare:workers';\nexport const load = () => ({ kv: await env.MY_KV.get('k') });\n// after\nimport { env } from 'cloudflare:workers';\nexport const prerender = false;\nexport const load = () => ({ kv: await env.MY_KV.get('k') });","handlingStrategy":"try-catch","validationCode":"import { building } from '$app/environment';\n// ensure this route is not prerendered if it reads env\nexport const prerender = false;","typeGuard":"import { building } from '$app/environment';\nfunction canAccessWorkerEnv() {\n  return !building && typeof globalThis.__sveltekit_cloudflare_platform !== 'undefined';\n}","tryCatchPattern":"import { env } from 'cloudflare:workers';\nlet value;\ntry {\n  value = env.MY_KV;\n} catch (e) {\n  if (e.message.includes('prerenderable route')) {\n    value = undefined; // fallback for prerender/build context\n  } else {\n    throw e;\n  }\n}","preventionTips":["Set `export const prerender = false` on any route that touches cloudflare bindings","Never import or access `cloudflare:workers` env at module top level of shared code","Access bindings only inside load functions / API handlers that run at request time"],"tags":["cloudflare-workers","prerender","bindings","ssr"],"backgroundTag":"cloudflare-workers-env-during-prerender","analyzedSha":"03f1687fe612ce3d2d9131139b5b188d9cf90c64","analyzedAt":"2026-09-02T02:01:50.504Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}