n8n-io/n8n · error · Error

${varName} must be a positive integer, got "${raw}".

Error message

${varName} must be a positive integer, got "${raw}".

What it means

Thrown by parsePositiveInt (used for N8N_INSTANCE_AI_SANDBOX_CREATE_TIMEOUT_SECONDS and similar) when a present env value is not a positive integer. Empty/undefined is allowed (returns undefined → caller applies default). Fractional, zero, negative, non-numeric, NaN, or Infinity values are rejected.

Source

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

	);
}

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

1. Set the named variable to a positive whole number in the units the variable expects (seconds for CREATE_TIMEOUT_SECONDS).
2. Drop any unit suffix and any decimal portion.
3. If unsure of units, check the variable's documented unit (seconds vs ms).

Example fix

# before
export N8N_INSTANCE_AI_SANDBOX_CREATE_TIMEOUT_SECONDS=1.5m

# after — integer seconds
export N8N_INSTANCE_AI_SANDBOX_CREATE_TIMEOUT_SECONDS=900

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

if (!positiveIntValid(process.env.N8N_INSTANCE_AI_SANDBOX_CREATE_TIMEOUT_SECONDS)) {
  throw new Error('create-timeout must be a positive integer (seconds)');
}

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

try {
  resolveSandboxConfig(process.env);
} catch (e) {
  if (e instanceof Error && /must be a positive integer/.test(e.message)) {
    // unset to apply default, then retry
  } else throw e;
}

When it happens

Trigger: Setting the create-timeout to '1.5' (fractional), '0', '-10', '60s', or 'soon'; the var name in the message identifies which variable failed.

Common situations: Operator writes '30' meaning 30 minutes into a seconds field (actually 30 seconds); including a unit suffix; using a decimal where an integer is required.

Related errors

• N8N_INSTANCE_AI_SANDBOX_TIMEOUT must be a positive number of
• Invalid sandbox provider "${providerRaw}". Set N8N_INSTANCE_
• Model ID is required
• Invalid delegate sub-agent tool name "${name}": must start w
• ${toolName} requires resumeSubAgent and cancelSubAgent to be

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