sveltejs/kit · error · Error

Invalid value for environment variable ${name}: ${JSON.strin

Error message

Invalid value for environment variable ${name}: ${JSON.stringify(value)} (${description})

What it means

SvelteKit adapter-node validates timeout-related environment variables (e.g. SHUTDOWN_TIMEOUT) as non-negative integers in seconds. `parsing_error` is thrown when the value cannot be parsed into the expected type/format. The message includes the raw value and a description of what was expected.

Source

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

 * @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+$/;

/**
 * Throw a consistently-structured parsing error for environment variables.
 * @param {string} name
 * @param {any} value
 * @param {string} description
 * @returns {never}
 */
function parsing_error(name, value, description) {
	throw new Error(
		`Invalid value for environment variable ${name}: ${JSON.stringify(value)} (${description})`
	);
}

/**
 * Check the environment for a timeout value (non-negative integer) in seconds.
 * @param {string} name
 * @param {number} [fallback]
 * @returns {number | undefined}
 */
export function timeout_env(name, fallback) {
	const raw = env(name, fallback);
	if (!raw) {
		return fallback;
	}

	if (!integer_regexp.test(raw)) {
		parsing_error(name, raw, 'should be a non-negative integer');

View on GitHub (pinned to 03f1687fe6)

Solutions

Set the env variable to a plain non-negative integer number of seconds, e.g. 30
Remove surrounding quotes, whitespace, or unit suffixes from the value
If the value is intentionally optional, unset it entirely to use the default

Example fix

// before
SHUTDOWN_TIMEOUT=30s
// after
SHUTDOWN_TIMEOUT=30

Defensive patterns

Strategy: validation

Validate before calling

const v = process.env.SHUTDOWN_TIMEOUT;
if (v !== undefined && (!/^\d+$/.test(v.trim()))) {
  throw new Error(`SHUTDOWN_TIMEOUT must be a non-negative integer, got: ${v}`);
}

Type guard

function isValidTimeout(v) {
  return typeof v === 'string' && /^\d+$/.test(v.trim());
}

Try / catch

try {
  await server.listen(port);
} catch (err) {
  if (String(err.message).startsWith('Invalid value for environment variable')) {
    console.error('Fix the offending env var to a plain integer value');
    process.exit(1);
  }
  throw err;
}

Prevention

Use plain integers (seconds) with no units in env files
Lint .env files for quoted or spaced values
Document accepted formats in your deployment README

When it happens

Trigger: Setting an env var consumed by timeout_env (e.g. SHUTDOWN_TIMEOUT) to a non-integer, negative number, or non-numeric string like '10s' or 'ten'.

Common situations: Deployment platforms exporting values with units ('30s'), whitespace, quotes, or leaving a placeholder value in the env file.

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/5b05d54a68e7ed2e. Report an issue: GitHub.