sveltejs/kit · error · Error

You should change envPrefix (${env_prefix}) to avoid conflic

Error message

You should change envPrefix (${env_prefix}) to avoid conflicts with existing environment variables — unexpectedly saw ${name}

What it means

The node adapter validates at startup that the configured `envPrefix` does not collide with unrelated environment variables already present in `process.env`. Any variable starting with the prefix whose unprefixed name is not a known SvelteKit private env (like PRERENDER, PROTOCOL_HEADER, etc.) causes this throw, to prevent silently reading/writing unexpected variables. It protects against prefix choices like `PUBLIC_` that collide with app-level vars.

Source

Thrown at packages/adapter-node/src/env.js:28

	'HOST_HEADER',
	'PORT_HEADER',
	'BODY_SIZE_LIMIT',
	'SHUTDOWN_TIMEOUT',
	'IDLE_TIMEOUT',
	'KEEP_ALIVE_TIMEOUT',
	'HEADERS_TIMEOUT'
]);

const expected_unprefixed = new Set(['LISTEN_PID', 'LISTEN_FDS']);

export const env_prefix = ENV_PREFIX;

if (env_prefix) {
	for (const name in process.env) {
		if (name.startsWith(env_prefix)) {
			const unprefixed = name.slice(env_prefix.length);
			if (!expected.has(unprefixed)) {
				throw new Error(
					`You should change envPrefix (${env_prefix}) to avoid conflicts with existing environment variables — unexpectedly saw ${name}`
				);
			}
		}
	}
}

/**
 * @param {string} name
 * @param {any} [fallback]
 */
export function env(name, fallback) {
	const prefix = expected_unprefixed.has(name) ? '' : env_prefix;
	const prefixed = prefix + name;
	return prefixed in process.env ? process.env[prefixed] : fallback;
}

const integer_regexp = /^\d+$/;

View on GitHub (pinned to 03f1687fe6)

Solutions

Change the adapter's envPrefix option to something unique that doesn't overlap with existing env vars
Unset or rename the conflicting environment variable in the deployment environment
If the variable is a legitimate private SvelteKit env, verify the spelling of its unprefixed name matches the expected set

Example fix

// before
const config = { kit: { adapter: adapter({ envPrefix: 'PUBLIC_' }) } };
// after
const config = { kit: { adapter: adapter({ envPrefix: 'MY_PRIVATE_' }) } };

Defensive patterns

Strategy: validation

Validate before calling

const prefix = 'MY_PRIVATE_';
const expected = new Set(['PRERENDER', 'PROTOCOL_HEADER', 'HOST_HEADER', 'PORT_HEADER', 'BODY_SIZE_LIMIT', 'SHUTDOWN_TIMEOUT']);
const conflicts = Object.keys(process.env).filter(n => n.startsWith(prefix) && !expected.has(n.slice(prefix.length)));
if (conflicts.length) throw new Error(`envPrefix conflict: ${conflicts.join(', ')}`);

Try / catch

try {
  startServer();
} catch (err) {
  if (String(err.message).includes('change envPrefix')) {
    console.error('envPrefix collides with existing env vars; pick a more unique prefix');
    process.exit(1);
  }
  throw err;
}

Prevention

Pick a distinctive prefix unlikely to collide (include your app name)
Audit `env | grep ^PREFIX` in the target deployment before release
Keep the prefix long and app-scoped, not generic like PUBLIC_

When it happens

Trigger: Starting the built server with a private env var set whose name starts with envPrefix but whose unprefixed name is not in the expected set of private env variables.

Common situations: Configuring envPrefix as 'PUBLIC_' or a very short prefix in adapter options, then setting unrelated shell/CI variables that happen to start with it.

Related errors

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