n8n-io/n8n · error · ValueError

Environment variable {env_name} must be an integer, got '{va

Error message

Environment variable {env_name} must be an integer, got '{value}'

What it means

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.

Source

Thrown at packages/@n8n/task-runner-python/src/env.py:36

    return None


def read_str_env(env_name: str, default: str) -> str:
    value = read_env(env_name)
    if value is None:
        return default
    return value


def read_int_env(env_name: str, default: int) -> int:
    value = read_env(env_name)
    if value is None:
        return default
    try:
        return int(value)
    except ValueError:
        raise ValueError(
            f"Environment variable {env_name} must be an integer, got '{value}'"
        )


def read_bool_env(env_name: str, default: bool) -> bool:
    value = read_env(env_name)
    if value is None:
        return default
    return value.strip().lower() == "true"


def read_float_env(env_name: str, default: float) -> float:
    value = read_env(env_name)
    if value is None:
        return default
    try:
        return float(value)
    except ValueError:

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Set the environment variable to a valid integer string (e.g. '8080' not '80.80' or '8O80').
2. Remove any unit suffixes — the code expects a bare integer.
3. Check for letter/digit confusion (O vs 0, l vs 1).
4. If the value comes from a template, validate it is numeric before deployment.

Example fix

# before
export N8N_RUNNERS_TASK_TIMEOUT='6O'  # letter O
# after
export N8N_RUNNERS_TASK_TIMEOUT='60'

def validate_int_env(name: str, default: int) -> int:
    raw = os.environ.get(name)
    if raw is None:
        return default
    try:
        return int(raw)
    except ValueError:
        raise ValueError(f'{name} must be an integer, got {raw!r}')

# Use before the runner reads it
validate_int_env('N8N_RUNNERS_TASK_TIMEOUT', 60)

from env import read_int_env

try:
    port = read_int_env('N8N_RUNNERS_HEALTH_CHECK_SERVER_PORT', 8080)
except ValueError as e:
    print(f'Environment error: {e}')
    sys.exit(1)

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Environment variable {env_name} must be a float, got '{value
• Environment variable N8N_RUNNERS_GRANT_TOKEN is required
• Task timeout must be positive, got {task_timeout}
• Auto shutdown timeout must be non-negative, got {auto_shutdo
• Graceful shutdown timeout must be positive, got {graceful_sh

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