zylon-ai/private-gpt · error · ImportError

Redis semaphore dependencies are not installed. Install with

Error message

Redis semaphore dependencies are not installed. Install with `uv sync --inexact --extra redis`.

What it means

The concurrency registry lazily imports RedisSemaphoreManager; if the optional redis extra is not installed, the ImportError is re-raised as a friendlier message telling you exactly how to install it (uv sync --inexact --extra redis). It fires only when settings actually select the redis concurrency backend.

Source

Thrown at private_gpt/components/concurrency/registry.py:28

logger = logging.getLogger(__name__)

SemaphoreManagerProvider = Callable[
    [Settings | None, int | None, str | None], SemaphoreManager
]


def _redis_semaphore_provider(
    settings: Settings | None,
    max_concurrency: int | None,
    queue_key: str | None,
) -> SemaphoreManager:
    try:
        from private_gpt.components.concurrency.redis_semaphore_manager import (
            RedisSemaphoreManager,
        )
    except ImportError as e:
        raise ImportError(
            format_missing_dependency_message("Redis semaphore", extras="redis")
        ) from e

    logger.info("Using RedisSemaphoreManager for concurrency control")
    return RedisSemaphoreManager(
        settings=settings,
        max_concurrency=max_concurrency,
        queue_key=queue_key,
    )


def _memory_semaphore_provider(
    settings: Settings | None,
    max_concurrency: int | None,
    queue_key: str | None,
) -> SemaphoreManager:
    del settings
    from private_gpt.components.concurrency.memory_semaphore_manager import (

View on GitHub (pinned to 4a030776a3)

Solutions

Install the extra: uv sync --inexact --extra redis (as the message says)
Or switch settings to the in-memory semaphore provider if Redis is not actually needed
Add the redis extra to the deployment's install command / Dockerfile so it's always present
Add a startup check that fails fast when the selected backend's deps are missing

Example fix

# before
# settings select redis semaphore, deps missing

# after
uv sync --inexact --extra redis
# or in settings: concurrency.backend = "memory"

Defensive patterns

Strategy: validation

Validate before calling

if settings.concurrency.backend == "redis":
    try:
        import redis  # noqa: F401  (proxy for the redis extra)
    except ImportError:
        raise ConfigError("run `uv sync --inexact --extra redis` before enabling redis concurrency")

Try / catch

try:
    manager = semaphore_registry.get_manager(settings)
except ImportError as e:
    if "extra redis" in str(e):
        raise ConfigError("Redis extra missing — install with `uv sync --inexact --extra redis` or use the memory backend") from e
    raise

Prevention

Install extras in the same step that enables their settings (Dockerfile/IaC)
Add a startup dependency check for every optional backend in settings
Keep slim images consistent with the selected concurrency backend

When it happens

Trigger: Configuring concurrency/semaphore settings to use the Redis backend in an environment where the redis optional dependencies are absent, triggering _redis_semaphore_provider's import.

Common situations: Enabling Redis-based concurrency in a deployment installed without the redis extra; CI or slim Docker images trimming extras; local dev on a machine that never ran uv sync with the extra.

Related errors

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