ruvnet/RuView · error · ValueError

Stream FPS must be between 1 and 60

Error message

Stream FPS must be between 1 and 60

What it means

Pydantic v2 @field_validator on Settings.stream_fps in archive/v1/src/config/settings.py. It enforces 1 <= stream_fps <= 60, matching the domain-level StreamingConfig.fps validator. An invalid STREAM_FPS env value fails Settings() construction at startup. fps=0 (a naive way to disable streaming) and 120 (high-framerate setups) are the typical rejects.

Source

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

        allowed_levels = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
        if v.upper() not in allowed_levels:
            raise ValueError(f"Log level must be one of: {allowed_levels}")
        return v.upper()
    
    @field_validator("pose_confidence_threshold")
    @classmethod
    def validate_confidence_threshold(cls, v):
        """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
    

View on GitHub (pinned to 4685618388)

Solutions

1. Set STREAM_FPS to an integer between 1 and 60
2. Disable streaming via the stream lifecycle endpoints (POST /stream/never-start or simply do not start it), not fps=0
3. Cap imported configs: min(fps, 60)
4. If the deployment truly needs >60 fps, raise the validator bound and load-test the pipeline

Example fix

# before
STREAM_FPS=0

# after
STREAM_FPS=30

raw = int(os.environ.get("STREAM_FPS", "30"))
assert 1 <= raw <= 60, f"STREAM_FPS must be 1-60, got {raw} (use the service lifecycle, not fps=0, to disable streaming)"

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

from pydantic import ValidationError
try:
    settings = Settings()
except ValidationError as e:
    if any(err["loc"][-1] == "stream_fps" for err in e.errors()):
        raise SystemExit("stream_fps must be an integer between 1 and 60") from e
    raise

When it happens

Trigger: STREAM_FPS=0 to 'turn off' streaming; STREAM_FPS=120 imported from a 120Hz capture config; STREAM_FPS=-1 sentinel values; fractional values like 29.97 depending on the field's declared type.

Common situations: Reusing camera-capture configs with uncapped fps; disabling streams via fps instead of the service lifecycle; performance tuning that raises fps past the 60 cap.

Related errors

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

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