{"record":{"id":"48eb48ed1aa68604","repo":"sveltejs/kit","slug":"the-headers-file-should-be-placed-in-the-project","errorCode":null,"errorMessage":"The _headers file should be placed in the project root rather than the ${builder.config.files.assets} directory","messagePattern":"The _headers file should be placed in the project root rather than the (.+?) directory","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/adapter-cloudflare/index.js","lineNumber":39,"sourceCode":"/** @type {typeof import('./index.js').default} */\nexport default function (options = {}) {\n\t// Add a random query so we can reliably string-replace the stub\n\tconst stub_import =\n\t\timport.meta.resolve('./src/virtual-cloudflare-workers.js') + '?' + crypto.randomUUID();\n\treturn {\n\t\tname,\n\t\tasync adapt(builder) {\n\t\t\tif (\n\t\t\t\tfs.existsSync('_routes.json') ||\n\t\t\t\tfs.existsSync(`${builder.config.files.assets}/_routes.json`)\n\t\t\t) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t\"Cloudflare Pages' _routes.json should be configured from the adapter option of the SvelteKit plugin in your vite.config.js. See https://svelte.dev/docs/kit/adapter-cloudflare#Options-routes\"\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tif (fs.existsSync(`${builder.config.files.assets}/_headers`)) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`The _headers file should be placed in the project root rather than the ${builder.config.files.assets} directory`\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tif (fs.existsSync(`${builder.config.files.assets}/_redirects`)) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`The _redirects file should be placed in the project root rather than the ${builder.config.files.assets} directory`\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tconst { wrangler_config, building_for_cloudflare_pages } = validate_wrangler_config(\n\t\t\t\toptions.config\n\t\t\t);\n\n\t\t\tlet dest = builder.getBuildDirectory('cloudflare');\n\t\t\tlet worker_dest = `${dest}/_worker.js`;\n\t\t\tlet assets_binding = 'ASSETS';\n","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/sveltejs/kit/blob/03f1687fe612ce3d2d9131139b5b188d9cf90c64/packages/adapter-cloudflare/index.js#L21-L57","documentation":"The Cloudflare Pages adapter builds the static assets directory (`.svelte-kit/cloudflare` by default) from the project's output. Cloudflare Pages expects `_headers` files only at the top of the deployed output, so the adapter forbids placing one inside the generated assets directory where it would be copied verbatim and not honored at the root. It throws at adapt time when `builder.config.files.assets/_headers` exists. The file belongs in the project root (in `static/` or the configured assets source) so it ends up at the deployment root.","triggerScenarios":"Running `vite build` with the cloudflare adapter while a file named `_headers` exists directly inside `builder.config.files.assets` (the generated assets output directory, typically `.svelte-kit/cloudflare`) during the `adapt` phase.","commonSituations":"Developers copy `_headers` from another Cloudflare Pages setup into the adapter's output/assets directory, or a build script generates `_headers` into the assets folder instead of the project root/static directory. Also happens after moving from adapter-static, where output directory conventions differ.","solutions":["Delete the `_headers` file from the adapter's assets output directory (e.g. `.svelte-kit/cloudflare/_headers`).","Place `_headers` in the project root `static/` directory (or `config.kit.files.assets`) so it is copied to the deployment root.","Rebuild with `vite build` so the adapter re-runs and validates the corrected layout."],"exampleFix":"// before: .svelte-kit/cloudflare/_headers exists\n// rm .svelte-kit/cloudflare/_headers\n// after: move it to the static assets source\n// mv .svelte-kit/cloudflare/_headers static/_headers","handlingStrategy":"validation","validationCode":"import fs from 'node:fs';\nif (fs.existsSync('.svelte-kit/cloudflare/_headers')) {\n  throw new Error('Move _headers to static/ so it lands at the deployment root');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep `_headers` only in the `static/` (or configured assets source) directory","Never write generated files into `.svelte-kit/` — it is build output","Add a CI check asserting `_headers` exists at the expected source location before building"],"tags":["cloudflare-pages","adapter","build-time","config"],"backgroundTag":"cloudflare-pages-headers-redirects-misplaced","analyzedSha":"03f1687fe612ce3d2d9131139b5b188d9cf90c64","analyzedAt":"2026-09-02T02:01:50.504Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}