n8n-io/n8n · error · Error

N8N_INSTANCE_AI_SANDBOX_TIMEOUT must be a positive number of

Error message

N8N_INSTANCE_AI_SANDBOX_TIMEOUT must be a positive number of ms, got "${raw}".

What it means

Thrown by parseTimeout when N8N_INSTANCE_AI_SANDBOX_TIMEOUT is set to a value that is not a finite positive number (ms). Empty/undefined is allowed (returns the default), but a present non-numeric, zero, negative, NaN, or Infinity value is rejected.

Source

Thrown at packages/@n8n/instance-ai/evaluations/harness/sandbox-config.ts:93

			enabled: true,
			provider: 'n8n-sandbox',
			serviceUrl,
			...(apiKey ? { apiKey } : {}),
			timeout,
		};
	}

	const exhaustiveProvider: never = provider;
	throw new Error(
		`Invalid sandbox provider "${String(exhaustiveProvider)}". Set N8N_INSTANCE_AI_SANDBOX_PROVIDER to one of: ${VALID_PROVIDERS.join(', ')}.`,
	);
}

function parseTimeout(raw: string | undefined): number | undefined {
	if (raw === undefined || raw === '') return undefined;
	const n = Number(raw);
	if (!Number.isFinite(n) || n <= 0) {
		throw new Error(
			`N8N_INSTANCE_AI_SANDBOX_TIMEOUT must be a positive number of ms, got "${raw}".`,
		);
	}
	return n;
}

function parsePositiveInt(raw: string | undefined, varName: string): number | undefined {
	if (raw === undefined || raw === '') return undefined;
	const n = Number(raw);
	if (!Number.isFinite(n) || n <= 0 || !Number.isInteger(n)) {
		throw new Error(`${varName} must be a positive integer, got "${raw}".`);
	}
	return n;
}

View on GitHub (pinned to 5ac6606e81)

Solutions

Set N8N_INSTANCE_AI_SANDBOX_TIMEOUT to a positive integer number of milliseconds, e.g. 300000 for 5 minutes.
If you wrote seconds, multiply by 1000.
Remove units/suffixes — only a bare number is accepted.

Example fix

# before
export N8N_INSTANCE_AI_SANDBOX_TIMEOUT=300s

# after — milliseconds, no unit
export N8N_INSTANCE_AI_SANDBOX_TIMEOUT=300000

Defensive patterns

Strategy: validation

Validate before calling

function timeoutValid(raw: string | undefined): boolean {
  if (raw === undefined || raw === '') return true; // default applies
  const n = Number(raw);
  return Number.isFinite(n) && n > 0;
}

if (!timeoutValid(process.env.N8N_INSTANCE_AI_SANDBOX_TIMEOUT)) {
  throw new Error('timeout must be positive finite ms');
}

Type guard

function isPositiveMs(raw: string): boolean {
  const n = Number(raw);
  return Number.isFinite(n) && n > 0;
}

Try / catch

try {
  resolveSandboxConfig(process.env);
} catch (e) {
  if (e instanceof Error && /N8N_INSTANCE_AI_SANDBOX_TIMEOUT/.test(e.message)) {
    delete process.env.N8N_INSTANCE_AI_SANDBOX_TIMEOUT; // fall back to default
    resolveSandboxConfig(process.env);
  } else throw e;
}

Prevention

Document that the unit is milliseconds, not seconds.
Reject unit suffixes in env-var linting.
Provide the default value in config templates so operators rarely set it.

When it happens

Trigger: Setting the timeout to '0', '-1', 'abc', '5s' (units are not supported — raw ms only), or 'Infinity'.

Common situations: Operator expects seconds and writes '300' meaning 300s but getting 300ms; typo including a unit suffix; copy-pasting a value formatted for a different tool.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of n8n-io/n8n@5ac6606e81 (2026-08-12). Data as JSON: /api/errors/6603b493d4034d61. Report an issue: GitHub.