sveltejs/kit · error · Error

Invalid environment variable name ${JSON.stringify(name)}

Error message

Invalid environment variable name ${JSON.stringify(name)}

What it means

Keys of the `variables` object exported from src/env.js must be valid JavaScript identifiers and must not collide with reserved names (like `$env` internals or build-injected names). SvelteKit throws when a name fails the identifier regex or is in the reserved set, since these become real module bindings injected into `$env/*` imports.

Source

Thrown at packages/kit/src/core/env.js:93

	let variables;

	const runner = get_runner(vite, server);

	/** @type {typeof import('../runtime/app/env/server.js')} */ (
		await runner.import(`${runtime_directory}/app/env/server.js`)
	).set_building();

	try {
		({ variables } = await runner.import(file));

		if (!variables || typeof variables !== 'object') {
			throw new Error(`${file} must export a variables object`);
		}

		// validate
		for (const name of Object.keys(variables)) {
			if (!valid_identifier.test(name) || reserved.has(name)) {
				throw new Error(`Invalid environment variable name ${JSON.stringify(name)}`);
			}
		}
	} catch (e) {
		const error = /** @type {any} */ (e || {});

		if (
			error.code === 'ERR_MODULE_NOT_FOUND' &&
			error.message?.includes(`Cannot find module '$app`)
		) {
			throw new Error(
				`Cannot import \`$app/*\` modules other than \`$app/env\` inside \`src/env\``,
				{ cause: e }
			);
		}

		throw error;
	} finally {
		await server.close();

View on GitHub (pinned to 03f1687fe6)

Solutions

1. Rename the key to a valid identifier: uppercase letters, digits, underscores, not starting with a digit (e.g. 'MY_VAR').
2. Keep the actual env var name matching, renaming it in the deployment environment too.
3. Check the name against reserved SvelteKit/internal names if it looks like a normal identifier but still fails.

Example fix

// before (src/env.js)
export const variables = { 'my-app-key': 'string' };
// after
export const variables = { MY_APP_KEY: 'string' };

const valid_identifier = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
const reserved = new Set(['default', 'variables']);
for (const name of Object.keys(variables)) {
  if (!valid_identifier.test(name) || reserved.has(name)) {
    throw new Error(`Invalid env variable name: ${name}`);
  }
}

function isValidEnvName(name) {
  return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) && name === name.toUpperCase();
}

try {
  await build();
} catch (e) {
  if (String(e.message).startsWith('Invalid environment variable name')) {
    console.error('Rename the env key to a valid UPPER_SNAKE_CASE identifier:', e.message);
  } else throw e;
}

When it happens

Trigger: Declaring an env variable key with dashes, dots, spaces, leading digits (e.g. `'MY-VAR': 'string'`), or a reserved word/name in src/env.js variables.

Common situations: Copy-pasting raw .env keys like `my-app-key` into the variables object; using JS reserved words like `class` or `delete`; accidental whitespace in keys.

Related errors

• Invalid field name ${path}: field names are written in JS ob
• Invalid value for environment variable ${env_prefix + name}:
• routes.include and routes.exclude must be arrays
• Invalid value for environment variable ${name}: ${JSON.strin
• Invalid isr.expiration value: ${JSON.stringify(value)} (${de

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