BerriAI/litellm · error · ValueError

Either 'host' or 'url' must be specified for redis.

Error message

Either 'host' or 'url' must be specified for redis.

What it means

In litellm/_redis.py's kwargs normalization (the function returning redis_kwargs for cache init): if 'url' is provided, host/port/db/password are stripped; elif startup_nodes or sentinel_nodes are present, host is not required; otherwise host must be present — ValueError("Either 'host' or 'url' must be specified for redis.") when the caller passed neither.

Solutions

  1. Pass url=... (redis:// or rediss://...) to RedisCache / redis_settings
  2. Or pass host= (and port=) explicitly
  3. For cluster mode, pass startup_nodes=[{"host": ..., "port": ...}] (correctly spelled) so the host requirement is waived
  4. For sentinel, pass sentinel_nodes=... (handled by the sentinel initializer)

Example fix

# before
RedisCache(port=6379, password="x")  # no host, no url -> ValueError

# after
RedisCache(host="redis.internal", port=6379, password="x")
# or
RedisCache(url="redis://:x@redis.internal:6379/0")
Defensive patterns

Strategy: validation

Validate before calling

def validate_redis_kwargs(kwargs: dict) -> None:
    has_url = bool(kwargs.get("url"))
    has_host = bool(kwargs.get("host"))
    has_nodes = bool(kwargs.get("startup_nodes") or kwargs.get("sentinel_nodes"))
    if not (has_url or has_host or has_nodes):
        raise ValueError(
            "Redis misconfigured: provide url=..., host=..., startup_nodes=..., or sentinel_nodes=..."
        )

Prevention

When it happens

Trigger: Constructing RedisCache(...) or configuring cache in the proxy with only port/password/namespace but no host and no url; passing host=None explicitly; a config template where the host placeholder was left empty; for cluster use, intending startup_nodes but misspelling the key so it falls through to the host check.

Common situations: YAML cache config with cache: type: redis and incomplete redis_settings; copy-paste of RedisCache examples that rely on env vars while also passing partial kwargs; typos like startup_node (singular) bypassing the cluster branch.

Related errors

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/e3bcf06e973a9252. Report an issue: GitHub.

Appendix: source

Thrown at litellm/_redis.py:483

    if "url" in redis_kwargs and redis_kwargs["url"] is not None:
        # Only strip host/port/db/password when not routing to a cluster.
        # When startup_nodes is also present the cluster path takes priority and
        # needs the password for authentication.
        if not redis_kwargs.get("startup_nodes"):
            redis_kwargs.pop("host", None)
            redis_kwargs.pop("port", None)
            redis_kwargs.pop("db", None)
            redis_kwargs.pop("password", None)
    elif (
        "startup_nodes" in redis_kwargs
        and redis_kwargs["startup_nodes"] is not None
        or "sentinel_nodes" in redis_kwargs
        and redis_kwargs["sentinel_nodes"] is not None
    ):
        pass
    elif "host" not in redis_kwargs or redis_kwargs["host"] is None:
        raise ValueError("Either 'host' or 'url' must be specified for redis.")

    # litellm.print_verbose(f"redis_kwargs: {redis_kwargs}")
    return redis_kwargs


def init_redis_cluster(redis_kwargs) -> redis.RedisCluster:
    _redis_cluster_nodes_in_env: Final[str | None] = get_secret("REDIS_CLUSTER_NODES")
    if _redis_cluster_nodes_in_env is not None:
        try:
            redis_kwargs["startup_nodes"] = json.loads(_redis_cluster_nodes_in_env)
        except json.JSONDecodeError:
            raise ValueError(
                "REDIS_CLUSTER_NODES environment variable is not valid JSON. Please ensure it's properly formatted."
            )

    verbose_logger.debug("init_redis_cluster: startup nodes are being initialized.")
    from redis.cluster import ClusterNode

View on GitHub (pinned to 77b7c6c40c)