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

Netlify reads custom HTTP headers from a _headers file that must live in the publish (site root) directory. SvelteKit's static assets directory is where your own assets live, but the adapter generates/copies _headers itself; a user-supplied _headers inside the static directory would conflict or be ignored, so the adapter throws during adapt().

Source

Thrown at packages/adapter-netlify/index.js:47

const netlify_framework_serverless_path = '.netlify/v1/functions';
const netlify_framework_edge_path = '.netlify/v1/edge-functions';

const FUNCTION_PREFIX = 'sveltekit-';

/** @type {typeof import('./index.js').default} */
export default function ({ split = false, edge = edge_set_in_env_var } = {}) {
	return {
		name,
		async adapt(builder) {
			if (!builder.routes) {
				throw new Error(
					'@sveltejs/adapter-netlify >=2.x (possibly installed through @sveltejs/adapter-auto) requires @sveltejs/kit version 1.5 or higher. ' +
						'Either downgrade the adapter or upgrade @sveltejs/kit'
				);
			}

			if (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 (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 netlify_config = get_netlify_config();

			// "build" is the default publish directory when Netlify detects SvelteKit
			const publish = get_publish_directory(netlify_config, builder) || 'build';

			// empty out existing build directories
			rmSync(publish, { force: true, recursive: true });
			rmSync('.netlify/v1', { force: true, recursive: true });

View on GitHub (pinned to 03f1687fe6)

Solutions

1. Move _headers from the static directory to the project root
2. Merge any custom header rules into the project-root _headers file the adapter will copy to publish
3. Delete the file from static/ if the rules are already handled elsewhere

Example fix

// shell
git mv static/_headers ./_headers

import { existsSync } from 'node:fs';
if (existsSync('static/_headers')) throw new Error('Move static/_headers to the project root');

When it happens

Trigger: A file named _headers exists in the directory configured as kit.files.assets (usually `static`), detected by existsSync during adapt().

Common situations: Following generic Netlify docs that say to put _headers in the repo root or public folder, while SvelteKit's equivalent static folder is not the publish root; migrating a plain Netlify static site to SvelteKit keeping old _headers in static/.

Related errors

• The _redirects file should be placed in the project root rat
• Cannot use `split: true` alongside `edge: true`
• Failed to parse netlify.toml: ${err.message}
• The publish directory cannot be set to the site root. Please
• The _headers file should be placed in the project root rathe

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