{"record":{"id":"f031921fd1ffe418","repo":"n8n-io/n8n","slug":"varname-must-be-a-positive-integer-got-raw","errorCode":null,"errorMessage":"${varName} must be a positive integer, got \"${raw}\".","messagePattern":"(.+?) must be a positive integer, got \"(.+?)\"\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/@n8n/instance-ai/evaluations/harness/sandbox-config.ts","lineNumber":104,"sourceCode":"\t);\n}\n\nfunction parseTimeout(raw: string | undefined): number | undefined {\n\tif (raw === undefined || raw === '') return undefined;\n\tconst n = Number(raw);\n\tif (!Number.isFinite(n) || n <= 0) {\n\t\tthrow new Error(\n\t\t\t`N8N_INSTANCE_AI_SANDBOX_TIMEOUT must be a positive number of ms, got \"${raw}\".`,\n\t\t);\n\t}\n\treturn n;\n}\n\nfunction parsePositiveInt(raw: string | undefined, varName: string): number | undefined {\n\tif (raw === undefined || raw === '') return undefined;\n\tconst n = Number(raw);\n\tif (!Number.isFinite(n) || n <= 0 || !Number.isInteger(n)) {\n\t\tthrow new Error(`${varName} must be a positive integer, got \"${raw}\".`);\n\t}\n\treturn n;\n}\n","sourceCodeStart":86,"sourceCodeEnd":108,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/instance-ai/evaluations/harness/sandbox-config.ts#L86-L108","documentation":"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.","triggerScenarios":"Setting the create-timeout to '1.5' (fractional), '0', '-10', '60s', or 'soon'; the var name in the message identifies which variable failed.","commonSituations":"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.","solutions":["Set the named variable to a positive whole number in the units the variable expects (seconds for CREATE_TIMEOUT_SECONDS).","Drop any unit suffix and any decimal portion.","If unsure of units, check the variable's documented unit (seconds vs ms)."],"exampleFix":"# before\nexport N8N_INSTANCE_AI_SANDBOX_CREATE_TIMEOUT_SECONDS=1.5m\n\n# after — integer seconds\nexport N8N_INSTANCE_AI_SANDBOX_CREATE_TIMEOUT_SECONDS=900","handlingStrategy":"validation","validationCode":"function positiveIntValid(raw: string | undefined): boolean {\n  if (raw === undefined || raw === '') return true;\n  const n = Number(raw);\n  return Number.isFinite(n) && n > 0 && Number.isInteger(n);\n}\n\nif (!positiveIntValid(process.env.N8N_INSTANCE_AI_SANDBOX_CREATE_TIMEOUT_SECONDS)) {\n  throw new Error('create-timeout must be a positive integer (seconds)');\n}","typeGuard":"function isPositiveInt(raw: string): boolean {\n  const n = Number(raw);\n  return Number.isFinite(n) && n > 0 && Number.isInteger(n);\n}","tryCatchPattern":"try {\n  resolveSandboxConfig(process.env);\n} catch (e) {\n  if (e instanceof Error && /must be a positive integer/.test(e.message)) {\n    // unset to apply default, then retry\n  } else throw e;\n}","preventionTips":["State the unit (seconds) in the variable's documented name/description.","Strip unit suffixes before passing through, or reject them explicitly.","Add a startup env-var lint pass for integer fields."],"tags":["configuration","env-vars","validation","timeout"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}