zylon-ai/private-gpt · critical · ValueError

Visibility timeout should be greater than soft time limit

Error message

Visibility timeout should be greater than soft time limit

What it means

Config-validation ValueError from CelerySettings.validate_config: when soft_time_limit and visibility_timeout are both set, visibility_timeout must be >= soft_time_limit. With a Redis broker, a task still running past the visibility window gets redelivered to another worker — so the window must outlast any task that could hit its soft limit.

Source

Thrown at private_gpt/settings/settings.py:1177

    def validate_config(self) -> bool:
        # Check if visibility timeout is set when broker or backend is redis
        if self.broker_mode == "redis" or self.backend_mode == "redis":
            if not self.visibility_timeout:
                raise ValueError(
                    "Visibility timeout should be set when broker or backend is Redis"
                )

        if self.soft_time_limit:
            if self.hard_time_limit and self.soft_time_limit > self.hard_time_limit:
                raise ValueError(
                    "Soft time limit should be less than or equal to hard time limit"
                )

            if (
                self.visibility_timeout
                and self.visibility_timeout < self.soft_time_limit
            ):
                raise ValueError(
                    "Visibility timeout should be greater than soft time limit"
                )

        if self.hard_time_limit:
            if (
                self.visibility_timeout
                and self.visibility_timeout < self.hard_time_limit
            ):
                raise ValueError(
                    "Visibility timeout should be greater than hard time limit"
                )

        return True


class RedisSettings(BaseModel):
    host: str = Field(description="Redis host")
    username: str | None = Field(default=None, description="Redis username")

View on GitHub (pinned to 4a030776a3)

Solutions

Raise visibility_timeout to at least soft_time_limit (preferably well above, e.g. soft + headroom).
Or lower soft_time_limit if long tasks are not intended.
Re-check the pair whenever either value changes; keep visibility_timeout > hard_time_limit too (the next validator enforces that).
Restart workers after the change — visibility_timeout is applied at broker connection time.

Example fix

# before
celery:
  broker_mode: redis
  visibility_timeout: 60
  soft_time_limit: 300
# after
celery:
  broker_mode: redis
  visibility_timeout: 3600
  soft_time_limit: 300

Defensive patterns

Strategy: validation

Validate before calling

soft, vis = cfg['celery'].get('soft_time_limit'), cfg['celery'].get('visibility_timeout')
if soft and vis:
    assert vis >= soft, f'visibility_timeout ({vis}) must be >= soft_time_limit ({soft})'

Type guard

const visibilityCoversSoft = (c: { visibility_timeout?: number; soft_time_limit?: number }): boolean =>
  c.visibility_timeout == null || c.soft_time_limit == null || c.visibility_timeout >= c.soft_time_limit;

Prevention

Set visibility_timeout to hard_time_limit + headroom to satisfy all ordering checks at once.
Revisit the value whenever task duration limits change.
Monitor for duplicated task executions — the symptom of a too-small window.

When it happens

Trigger: Redis broker config with visibility_timeout: 60 and soft_time_limit: 300; adding task time limits to an existing Redis setup whose visibility_timeout was set barely above typical runtime; copying a visibility_timeout from a short-task example into a long-task deployment.

Common situations: Adding soft_time_limit after Redis was already configured; lowering visibility_timeout to reduce redelivery latency; per-env overrides drifting so only one of the two values is updated on deploys.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/b5d7156dd4f12171. Report an issue: GitHub.