zylon-ai/private-gpt · error · ImportError

Redis streaming dependencies are not installed. Install with

Error message

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

What it means

Raised by the Redis stream provider factory in streaming/registry.py when importing RedisStreamService (which needs the redis client library) fails with ImportError. The dependency is optional and shipped behind the 'redis' extra, so the message tells you the exact uv sync command to install it. The original ImportError is chained via 'from e'.

Source

Thrown at private_gpt/components/streaming/registry.py:18

from collections.abc import Callable

from private_gpt.components.streaming.providers.stream_service import StreamService
from private_gpt.settings.settings import Settings
from private_gpt.utils.dependencies import format_missing_dependency_message

StreamProvider = Callable[[Settings], StreamService]


def _redis_stream_provider(settings: Settings) -> StreamService:
    try:
        from private_gpt.components.streaming.providers.redis_stream_service import (
            LazyRedisClientFactory,
            RedisStreamConfig,
            RedisStreamService,
        )
    except ImportError as e:
        raise ImportError(
            format_missing_dependency_message(
                "Redis streaming",
                extras="redis",
            )
        ) from e

    config = RedisStreamConfig(
        redis_url=settings.redis.url + "/8",
        stream_prefix=settings.stream.stream_prefix,
        status_prefix=settings.stream.status_prefix,
        expiry_seconds=settings.stream.stream_expiration,
        max_stream_length=settings.stream.maximum_stream_length,
        minimum_connections=settings.stream.minimum_connections,
    )
    client = LazyRedisClientFactory.get_instance(config)
    return RedisStreamService(config=config, redis_client=client)

View on GitHub (pinned to 4a030776a3)

Solutions

Run: uv sync --inexact --extra redis
Verify the import works afterwards: python -c "import redis" (or import the provider module)
If you cannot install extras, switch settings.stream.broker back to the in-memory provider

Example fix

# before: broker=redis without deps, ImportError at startup
# terminal
uv sync --inexact --extra redis
# then restart the app with stream.broker: redis

Defensive patterns

Strategy: validation

Validate before calling

try:
    import redis  # noqa: F401
except ImportError:
    raise SystemExit(
        "stream.broker=redis requires the redis extra: uv sync --inexact --extra redis"
    )

Type guard

def redis_streaming_available() -> bool:
    try:
        import redis  # noqa: F401
        return True
    except ImportError:
        return False

Prevention

Add a dependency preflight check for optional extras at app startup
Include needed extras in Docker/CI images explicitly (--extra redis)

When it happens

Trigger: Configuring settings.stream.broker to the Redis provider in an environment where the redis package was never installed (default install excludes optional extras).

Common situations: Enabling Redis streaming in an existing deployment without reinstalling deps; CI images built without --extra redis; a venv synced before the redis support was added to settings.

Related errors

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