zylon-ai/private-gpt · error · ImportError

Redis cache dependencies are not installed. Install with `uv

Error message

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

What it means

ImportError raised by RedisCache.__init__ (private_gpt/components/cache/cache_service.py) when the optional `redis` Python package is not installed. The cache extra is decoupled from the base install; constructing RedisCache with cache settings pointing at Redis lazily imports redis and re-raises with an install instruction from format_missing_dependency_message.

Source

Thrown at private_gpt/components/cache/cache_service.py:80

        cache_key = self._key(namespace, key)
        expires_at = time.monotonic() + ttl_seconds if ttl_seconds is not None else None
        with self._lock:
            self._values[cache_key] = (expires_at, value)
            self._values.move_to_end(cache_key)
            while len(self._values) > self._max_entries:
                self._values.popitem(last=False)

    def delete(self, namespace: str, key: str) -> None:
        with self._lock:
            self._values.pop(self._key(namespace, key), None)


class RedisCache:
    def __init__(self, settings: Settings) -> None:
        try:
            import redis
        except ImportError as error:
            raise ImportError(
                format_missing_dependency_message("Redis cache", extras="redis")
            ) from error

        redis_database = (
            settings.cache.redis_database
            if settings.cache.redis_database is not None
            else int(settings.redis.database or 0)
        )
        self._prefix = settings.cache.key_prefix
        self._client = redis.Redis.from_url(
            settings.redis.url,
            db=redis_database,
            decode_responses=False,
        )

    def _key(self, namespace: str, key: str) -> str:
        digest = hashlib.sha256(key.encode()).hexdigest()
        return f"{self._prefix}:{namespace}:{digest}"

View on GitHub (pinned to 4a030776a3)

Solutions

Install the extra exactly as the message says: `uv sync --inexact --extra redis`.
With pip: `pip install 'private-gpt[redis]'` or `pip install redis`.
If Redis is not intended, revert the cache settings to the memory backend so RedisCache is never constructed.
Ensure deployment Dockerfiles/CI include the redis extra.

Example fix

// before
# settings: cache backend = redis, base install
cache = RedisCache(settings)  # ImportError

// after
$ uv sync --inexact --extra redis
cache = RedisCache(settings)

Defensive patterns

Strategy: validation

Validate before calling

try:
    import redis  # noqa: F401
    HAS_REDIS = True
except ImportError:
    HAS_REDIS = False

if settings.cache.backend == "redis" and not HAS_REDIS:
    raise RuntimeError("Run `uv sync --inexact --extra redis` before enabling the redis cache")

Try / catch

try:
    cache = RedisCache(settings)
except ImportError as e:
    raise RuntimeError("Install the redis extra: uv sync --inexact --extra redis") from e

Prevention

Sync extras whenever you enable redis cache settings.
Beware exact `uv sync` pruning extras after lock changes — use --inexact.
Include extras in Dockerfile/CI install steps.
Fail fast at startup with an import probe rather than at first request.

When it happens

Trigger: Setting PGPT_SETTINGS cache backend/type to redis (or a profile enabling RedisCache) without having run an extra-enabled install; calling RedisCache(settings) in tests on a base-install environment.

Common situations: Switching from in-memory/LRUCache to redis in settings.yaml without reinstalling dependencies; fresh clones deployed with plain `uv sync` (exact) which drops extras after a lock change; CI environments not passing the redis extra.

Related errors

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