ruvnet/RuView · error · ValueError

Port must be between 1 and 65535

Error message

Port must be between 1 and 65535

What it means

Pydantic v2 @field_validator on Settings.port in archive/v1/src/config/settings.py. It enforces 1 <= port <= 65535 (the valid TCP/UDP port range). An invalid PORT env value raises ValueError at Settings() construction and prevents application startup. Note this is the API port; the database port has its own separate validator.

Source

Thrown at archive/v1/src/config/settings.py:215

        """Validate confidence threshold."""
        if not 0.0 <= v <= 1.0:
            raise ValueError("Confidence threshold must be between 0.0 and 1.0")
        return v
    
    @field_validator("stream_fps")
    @classmethod
    def validate_stream_fps(cls, v):
        """Validate streaming FPS."""
        if not 1 <= v <= 60:
            raise ValueError("Stream FPS must be between 1 and 60")
        return v
    
    @field_validator("port")
    @classmethod
    def validate_port(cls, v):
        """Validate port number."""
        if not 1 <= v <= 65535:
            raise ValueError("Port must be between 1 and 65535")
        return v
    
    @field_validator("workers")
    @classmethod
    def validate_workers(cls, v):
        """Validate worker count."""
        if v < 1:
            raise ValueError("Workers must be at least 1")
        return v
    
    @field_validator("db_port")
    @classmethod
    def validate_db_port(cls, v):
        """Validate database port."""
        if not 1 <= v <= 65535:
            raise ValueError("Database port must be between 1 and 65535")
        return v
    

View on GitHub (pinned to 4685618388)

Solutions

1. Set PORT to a value in 1-65535 (unprivileged apps commonly use 8000 or 8080)
2. If you wanted an ephemeral port (0), let the OS assign it at bind time instead of via this setting
3. Double the digits check: grep the .env/compose file for 5-digit ports above 65535
4. Prefer 1024-65535 unless the process deliberately runs as root for privileged ports

Example fix

# before
PORT=80080

# after
PORT=8080

raw = int(os.environ.get("PORT", "8000"))
assert 1 <= raw <= 65535, f"PORT must be 1-65535, got {raw} (5-digit values above 65535 are usually typos)"

def is_valid_port(v) -> bool:
    return isinstance(v, int) and not isinstance(v, bool) and 1 <= v <= 65535

from pydantic import ValidationError
try:
    settings = Settings()
except ValidationError as e:
    if any(err["loc"][-1] == "port" for err in e.errors()):
        raise SystemExit("PORT must be in 1-65535; port 0 (ephemeral) is not supported via settings") from e
    raise

When it happens

Trigger: PORT=0 (attempting an ephemeral/dynamic port assignment); PORT=80080 or 99999 (digit-doubling typos); PORT=65536 (classic off-by-one at the range edge); negative values.

Common situations: Docker/K8s configs that use host port 0 for auto-assignment being copied into the app's own PORT; typos in .env files; port-scanner or proxy configs using out-of-range placeholder values; copying an internal service mesh port like 90000 from documentation.

Related errors

• Environment must be one of: {allowed_environments}
• Log level must be one of: {allowed_levels}
• Confidence threshold must be between 0.0 and 1.0
• Stream FPS must be between 1 and 60
• Workers must be at least 1

AI-assisted analysis of ruvnet/RuView@4685618388 (2026-08-16). Data as JSON: /api/errors/8c00ee2810e53a20. Report an issue: GitHub.