sveltejs/kit · error · Error

The _headers file should be placed in the project root rathe

Error message

The _headers file should be placed in the project root rather than the ${builder.config.files.assets} directory

What it means

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.

Source

Thrown at packages/adapter-cloudflare/index.js:39

/** @type {typeof import('./index.js').default} */
export default function (options = {}) {
	// Add a random query so we can reliably string-replace the stub
	const stub_import =
		import.meta.resolve('./src/virtual-cloudflare-workers.js') + '?' + crypto.randomUUID();
	return {
		name,
		async adapt(builder) {
			if (
				fs.existsSync('_routes.json') ||
				fs.existsSync(`${builder.config.files.assets}/_routes.json`)
			) {
				throw new Error(
					"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"
				);
			}

			if (fs.existsSync(`${builder.config.files.assets}/_headers`)) {
				throw new Error(
					`The _headers file should be placed in the project root rather than the ${builder.config.files.assets} directory`
				);
			}

			if (fs.existsSync(`${builder.config.files.assets}/_redirects`)) {
				throw new Error(
					`The _redirects file should be placed in the project root rather than the ${builder.config.files.assets} directory`
				);
			}

			const { wrangler_config, building_for_cloudflare_pages } = validate_wrangler_config(
				options.config
			);

			let dest = builder.getBuildDirectory('cloudflare');
			let worker_dest = `${dest}/_worker.js`;
			let assets_binding = 'ASSETS';

View on GitHub (pinned to 03f1687fe6)

Solutions

1. Delete the `_headers` file from the adapter's assets output directory (e.g. `.svelte-kit/cloudflare/_headers`).
2. Place `_headers` in the project root `static/` directory (or `config.kit.files.assets`) so it is copied to the deployment root.
3. Rebuild with `vite build` so the adapter re-runs and validates the corrected layout.

Example fix

// before: .svelte-kit/cloudflare/_headers exists
// rm .svelte-kit/cloudflare/_headers
// after: move it to the static assets source
// mv .svelte-kit/cloudflare/_headers static/_headers

import fs from 'node:fs';
if (fs.existsSync('.svelte-kit/cloudflare/_headers')) {
  throw new Error('Move _headers to static/ so it lands at the deployment root');
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• The _redirects file should be placed in the project root rat
• The `edge` runtime is no longer supported
• ${relative} does not exist
• ${relative} is missing ${tag}
• The SvelteKit Vite plugin ${keypath} should be an object wit

AI-assisted analysis of sveltejs/kit@03f1687fe6 (2026-09-02). Data as JSON: /api/errors/48eb48ed1aa68604. Report an issue: GitHub.