{"record":{"id":"fbac1fe2303794ce","repo":"n8n-io/n8n","slug":"environment-variable-env-name-must-be-an-integer","errorCode":null,"errorMessage":"Environment variable {env_name} must be an integer, got '{value}'","messagePattern":"Environment variable (.+?) must be an integer, got '(.+?)'","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"packages/@n8n/task-runner-python/src/env.py","lineNumber":36,"sourceCode":"\n    return None\n\n\ndef read_str_env(env_name: str, default: str) -> str:\n    value = read_env(env_name)\n    if value is None:\n        return default\n    return value\n\n\ndef read_int_env(env_name: str, default: int) -> int:\n    value = read_env(env_name)\n    if value is None:\n        return default\n    try:\n        return int(value)\n    except ValueError:\n        raise ValueError(\n            f\"Environment variable {env_name} must be an integer, got '{value}'\"\n        )\n\n\ndef read_bool_env(env_name: str, default: bool) -> bool:\n    value = read_env(env_name)\n    if value is None:\n        return default\n    return value.strip().lower() == \"true\"\n\n\ndef read_float_env(env_name: str, default: float) -> float:\n    value = read_env(env_name)\n    if value is None:\n        return default\n    try:\n        return float(value)\n    except ValueError:","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/task-runner-python/src/env.py#L18-L54","documentation":"Thrown by read_int_env in the Python task runner when an environment variable expected to be an integer cannot be parsed as one. The function reads the raw string value and attempts int(value); on ValueError it re-raises with a descriptive message including the variable name and the offending value. This guards every integer-typed config field at startup.","triggerScenarios":"Any environment variable read via read_int_env (e.g. port, timeout, concurrency settings) is set to a non-numeric string like 'abc', '12.5', 'true', or an empty string that isn't handled by a default. int(value) raises ValueError, caught and re-raised.","commonSituations":"Typo in an environment variable value (e.g. '6O80' with letter O instead of zero). Using a float string like '30.5' for a field that expects an integer. Setting a boolean-like value ('true', 'false') for a numeric field. Accidentally including units like '30s' when the code expects a bare number.","solutions":["Set the environment variable to a valid integer string (e.g. '8080' not '80.80' or '8O80').","Remove any unit suffixes — the code expects a bare integer.","Check for letter/digit confusion (O vs 0, l vs 1).","If the value comes from a template, validate it is numeric before deployment."],"exampleFix":"# before\nexport N8N_RUNNERS_TASK_TIMEOUT='6O'  # letter O\n# after\nexport N8N_RUNNERS_TASK_TIMEOUT='60'","handlingStrategy":"validation","validationCode":"def validate_int_env(name: str, default: int) -> int:\n    raw = os.environ.get(name)\n    if raw is None:\n        return default\n    try:\n        return int(raw)\n    except ValueError:\n        raise ValueError(f'{name} must be an integer, got {raw!r}')\n\n# Use before the runner reads it\nvalidate_int_env('N8N_RUNNERS_TASK_TIMEOUT', 60)","typeGuard":null,"tryCatchPattern":"from env import read_int_env\n\ntry:\n    port = read_int_env('N8N_RUNNERS_HEALTH_CHECK_SERVER_PORT', 8080)\nexcept ValueError as e:\n    print(f'Environment error: {e}')\n    sys.exit(1)","preventionTips":["Use numeric-only values for integer environment variables.","Validate environment variables in deployment scripts before applying.","Avoid unit suffixes — the code expects bare integers."],"tags":["task-runner","python","configuration","env-var","type-error","startup"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}