sveltejs/kit · error · Error

You must specify the `assets.binding` key in ${config_path}

Error message

You must specify the `assets.binding` key in ${config_path} before deploying your Worker. Consult https://developers.cloudflare.com/workers/static-assets/binding/#binding

What it means

When a Worker (`main`) is deployed alongside static assets, an `assets.binding` must be defined so the Worker script can fetch static assets through an env binding (typically ASSETS). Validation fails during build if `main` is set but `assets.binding` is missing.

Source

Thrown at packages/adapter-cloudflare/utils.js:41

	const config_path = wrangler_config.configPath || 'your wrangler.jsonc file';

	// we don't support workers sites
	if (wrangler_config.site) {
		throw new Error(
			`You must remove all \`site\` keys in ${config_path}. Consult https://svelte.dev/docs/kit/adapter-cloudflare#Migrating-from-Workers-Sites`
		);
	}

	// we need the `assets.directory` key so that the static assets are deployed
	if ((wrangler_config.main || wrangler_config.assets) && !wrangler_config.assets?.directory) {
		throw new Error(
			`You must specify the \`assets.directory\` key in ${config_path}. Consult https://developers.cloudflare.com/workers/static-assets/binding/#directory`
		);
	}

	// we need the `assets.binding` key so that the Worker can access the static assets
	if (wrangler_config.main && !wrangler_config.assets?.binding) {
		throw new Error(
			`You must specify the \`assets.binding\` key in ${config_path} before deploying your Worker. Consult https://developers.cloudflare.com/workers/static-assets/binding/#binding`
		);
	}

	// the user might have forgot the `main` key or should remove the `assets.binding`
	// key to deploy static assets without a Worker
	if (!wrangler_config.main && wrangler_config.assets?.binding) {
		throw new Error(
			`You must specify the \`main\` key in ${config_path} if you want to deploy a Worker alongside your static assets. Otherwise, remove the \`assets.binding\` key if you only want to deploy static assets.`
		);
	}
}

/**
 * Extracts the redirect source from each line of a [_redirects](https://developers.cloudflare.com/pages/configuration/redirects/)
 * file so we can exclude them in [_routes.json](https://developers.cloudflare.com/pages/functions/routing/#create-a-_routesjson-file)
 * to ensure the redirect is invoked instead of the Cloudflare Worker.
 * @param {string} file_contents

View on GitHub (pinned to 03f1687fe6)

Solutions

1. Add `"binding": "ASSETS"` inside the `assets` object in wrangler.jsonc.
2. Access the assets through `platform.env.ASSETS.fetch(...)` in your worker code with that binding name.
3. If you don't actually need a Worker script, remove `main` instead so assets deploy alone.

Example fix

// before
{
  "main": "build/server/index.js",
  "assets": { "directory": ".svelte-kit/cloudflare" }
}

// after
{
  "main": "build/server/index.js",
  "assets": { "directory": ".svelte-kit/cloudflare", "binding": "ASSETS" }
}

if (cfg.main && !cfg.assets?.binding) {
  throw new Error('wrangler config needs assets.binding when main is set');
}

function workerCanAccessAssets(config) {
  return typeof config?.main === 'string' && typeof config?.assets?.binding === 'string';
}

try {
  await build();
} catch (e) {
  if (String(e).includes('`assets.binding`')) {
    console.error('Add assets.binding (e.g. "ASSETS") to wrangler config');
    process.exit(1);
  }
  throw e;
}

When it happens

Trigger: wrangler config has `main: "<worker entry>"` and `assets` (with directory) but no `assets.binding`, checked during `vite build` / deploy via validate_wrangler_config.

Common situations: Adding a custom worker entry to a previously static-only project; deleting the binding while keeping `main`; scaffolding configs from non-adapter templates.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• You must specify the `assets.directory` key in ${config_path
• You must specify the `main` key in ${config_path} if you wan
• You must remove all `site` keys in ${config_path}. Consult h
• The following _redirects rule cannot be excluded by _routes.
• routes.include and routes.exclude must be arrays

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