ruvnet/RuView · error · ValueError

Workers must be at least 1

Error message

Workers must be at least 1

What it means

Pydantic v2 @field_validator on Settings.workers in archive/v1/src/config/settings.py. It enforces workers >= 1; zero and negative values raise ValueError at Settings() construction. Zero-worker configs are usually accidental rather than intentional — most often a computed value that evaluated to 0 on a small host.

Source

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

        """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
    
    @field_validator("redis_port")
    @classmethod
    def validate_redis_port(cls, v):
        """Validate Redis port."""
        if not 1 <= v <= 65535:
            raise ValueError("Redis port must be between 1 and 65535")
        return v
    

View on GitHub (pinned to 4685618388)

Solutions

1. Set WORKERS to at least 1; use 1 to force serial processing
2. Fix computed values with a floor: max(1, os.cpu_count() - 1)
3. Audit deployment templates for WORKERS formulas that can evaluate to 0 on single-core instances
4. If you truly want no background workers, gate the feature elsewhere — this setting requires >= 1

Example fix

# before
WORKERS=0

# after
WORKERS=1

raw = int(os.environ.get("WORKERS", "4"))
assert raw >= 1, f"WORKERS must be >= 1, got {raw} (use 1 for serial processing; os.cpu_count()-1 yields 0 on single-core hosts)"

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

from pydantic import ValidationError
try:
    settings = Settings()
except ValidationError as e:
    if any(err["loc"][-1] == "workers" for err in e.errors()):
        raise SystemExit("workers must be at least 1; use max(1, cpu_count - 1) in derived configs") from e
    raise

When it happens

Trigger: WORKERS=0 set to 'disable background workers'; WORKERS computed as os.cpu_count() - 1 on a single-core host (0); WORKERS=-1 from an auto-scaling formula; WORKERS copied from a memory-constrained template that assumes division floors to at least 1.

Common situations: Deployment scripts deriving worker counts from CPU counts on small containers (1 vCPU); CI runners with 1 core; attempts to serialize processing by setting workers to zero instead of one.

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
• Port must be between 1 and 65535

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