n8n-io/n8n · error · ConfigurationError

Port must be between 0 and 65535, got {port}

Error message

Port must be between 0 and 65535, got {port}

What it means

Thrown by HealthCheckConfig.from_env when the health check server port read from the N8N_RUNNERS_HEALTH_CHECK_SERVER_PORT environment variable is outside the valid TCP port range [0, 65535]. This is a startup-time configuration validation that prevents the runner from attempting to bind to an impossible port.

Source

Thrown at packages/@n8n/task-runner-python/src/config/health_check_config.py:26

    ENV_HEALTH_CHECK_SERVER_ENABLED,
    ENV_HEALTH_CHECK_SERVER_HOST,
    ENV_HEALTH_CHECK_SERVER_PORT,
)


@dataclass
class HealthCheckConfig:
    enabled: bool
    host: str
    port: int

    @classmethod
    def from_env(cls):
        port = read_int_env(
            ENV_HEALTH_CHECK_SERVER_PORT, DEFAULT_HEALTH_CHECK_SERVER_PORT
        )
        if port < 0 or port > 65535:
            raise ConfigurationError(f"Port must be between 0 and 65535, got {port}")

        return cls(
            enabled=read_bool_env(ENV_HEALTH_CHECK_SERVER_ENABLED, default=False),
            host=read_str_env(
                ENV_HEALTH_CHECK_SERVER_HOST, DEFAULT_HEALTH_CHECK_SERVER_HOST
            ),
            port=port,
        )

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Set N8N_RUNNERS_HEALTH_CHECK_SERVER_PORT to a value between 0 and 65535 (commonly 1024-65535 for non-privileged).
2. If you want an OS-assigned port, use 0 (the OS will pick an available port at bind time).
3. Verify the value is not being overridden by a stray environment variable in your deployment config.
4. Check for typos or accidental truncation in the port value.

Example fix

# before
export N8N_RUNNERS_HEALTH_CHECK_SERVER_PORT=70000
# after
export N8N_RUNNERS_HEALTH_CHECK_SERVER_PORT=8080

import os

port = int(os.environ.get('N8N_RUNNERS_HEALTH_CHECK_SERVER_PORT', '0'))
if not (0 <= port <= 65535):
    raise ValueError(f'Port must be 0-65535, got {port}')

from config.task_runner_config import ConfigurationError

try:
    config = HealthCheckConfig.from_env()
except ConfigurationError as e:
    print(f'Configuration error: {e}')
    sys.exit(1)

When it happens

Trigger: The environment variable ENV_HEALTH_CHECK_SERVER_PORT is set to a negative number, a number greater than 65535, or a value that read_int_env parses to an out-of-range integer. The check `port < 0 or port > 65535` fires in the from_env classmethod before the HealthCheckConfig dataclass is constructed.

Common situations: Setting the port to a value like 70000 or -1 in a Docker compose file or Kubernetes manifest. Copying a config from a different system that uses a different port scheme. Accidentally setting the variable to a PID or other unrelated number.

Related errors

• Security violation detected
• Wildcard '*' in {list_name} must be used alone, not with oth
• 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

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