sveltejs/kit · error · Error

Invalid value for environment variable ${env_prefix + name}:

Error message

Invalid value for environment variable ${env_prefix + name}: ${JSON.stringify(value)} (expected ${expected})

What it means

The typed env helpers (boolean_env, number_env, bytes_env) validate the string value of a prefixed environment variable against the declared type. When the value cannot be parsed (e.g. 'yes' for a boolean, 'abc' for a number), parsing_error throws with the variable name, the raw value, and the expected format.

Source

Thrown at packages/adapter-bun/src/env.js:38

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

/**
 * @param {string} name
 * @param {string} value
 * @param {string} expected
 * @returns {never}
 */
function parsing_error(name, value, expected) {
	throw new Error(
		`Invalid value for environment variable ${env_prefix + name}: ${JSON.stringify(value)} (expected ${expected})`
	);
}

/**
 * @template {string | undefined} [T=undefined]
 * @param {string} name
 * @param {T} [fallback]
 * @returns {string | T}
 */
export function env(name, fallback) {
	const prefixed = env_prefix + name;
	return prefixed in process.env
		? /** @type {string} */ (process.env[prefixed])
		: /** @type {T} */ (fallback);
}

/** @type {Record<string, boolean>} */

View on GitHub (pinned to 03f1687fe6)

Solutions

Correct the environment variable value to the expected format shown in the message (e.g. true/false, plain integers, valid byte strings like '512b'/'10kb'/'1mb').
Check for hidden whitespace or stray quotes in the value: run `echo -n "$VAR" | xxd` to inspect it.
Unset the variable if it is optional, so the helper's default is used.

Example fix

// before
ORIGIN_LIMIT="1,000" node build
// after
ORIGIN_LIMIT=1000 node build

Defensive patterns

Strategy: validation

Validate before calling

function assertNumberEnv(v, name) {
  if (v === undefined) return;
  if (!/^-?\d+(\.\d+)?$/.test(v.trim())) throw new Error(`${name} must be a number, got ${JSON.stringify(v)}`);
}
assertNumberEnv(process.env.LIMIT, 'LIMIT');

Try / catch

try {
  startServer();
} catch (err) {
  if (/Invalid value for environment variable/.test(err.message)) {
    console.error('Fix the env var listed in the message and redeploy');
  }
  throw err;
}

Prevention

Document accepted formats (true/false, integers, byte strings) next to each env var.
Validate env vars in CI before deploying.
Beware shell quoting and stray whitespace in .env files.

When it happens

Trigger: Calling env('FLAG', 'boolean') where FLAG is set to something unparseable like 'trueish'; env('LIMIT', 'number') with '10s'; env('SIZE', 'bytes') with '10kb ' or other malformed byte strings.

Common situations: Typo or wrong-case boolean values (True/YES); human-friendly numbers like '1,000' or '10 MB'; shell quoting leaving stray spaces or quotes in the value.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

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