BerriAI/litellm · warning · ProxyException

503

503

Error message

Cache not initialized. litellm.cache is None

What it means

GET /cache/ping checks LiteLLM's cache subsystem before pinging anything: if the global litellm.cache is None (the proxy config has no cache_settings, so no cache object was constructed at startup) it raises a ProxyException with HTTP 503 whose JSON body says 'Cache not initialized. litellm.cache is None' plus empty cache params. It signals missing configuration, not a broken Redis connection.

Source

Thrown at litellm/proxy/caching_routes.py:62

        return masker.mask_dict(cleaned_params)
    except (AttributeError, TypeError) as e:
        verbose_proxy_logger.debug("Error extracting cache params: %s", e)
        return {}


@router.get(
    "/ping",
    response_model=CachePingResponse,
    dependencies=[Depends(user_api_key_auth)],
)
async def cache_ping():
    """
    Endpoint for checking if cache can be pinged
    """
    litellm_cache_params: dict[str, Any] = {}
    cleaned_cache_params: dict[str, Any] = {}
    if litellm.cache is None:
        raise ProxyException(
            message=safe_dumps(
                {
                    "message": "Cache not initialized. litellm.cache is None",
                    "litellm_cache_params": "{}",
                    "health_check_cache_params": "{}",
                }
            ),
            type=ProxyErrorTypes.cache_ping_error,
            param="cache_ping",
            code=503,
        )
    try:
        litellm_cache_params = masker.mask_dict(vars(litellm.cache))
        # remove field that might reference itself
        litellm_cache_params.pop("cache", None)
        cleaned_cache_params = _extract_cache_params()

        if litellm.cache.type == "redis":

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Add litellm_settings.cache_settings (type: redis plus host/port/password or url) to config.yaml and restart the proxy.
2. Confirm GET /cache/ping returns 200 with latency after restart.
3. If caching is genuinely unused, drop /cache/ping from monitoring to remove the noise.

Example fix

# before - config.yaml has no cache settings (litellm.cache stays None)
# after
litellm_settings:
  cache_settings:
    type: redis
    host: redis.example.com
    port: 6379
    password: os.environ/REDIS_PASSWORD

import httpx

def assert_cache_configured(base_url: str, api_key: str) -> None:
    r = httpx.get(f'{base_url}/cache/ping', headers={'Authorization': f'Bearer {api_key}'})
    if r.status_code == 503 and 'Cache not initialized' in r.text:
        raise RuntimeError('proxy has no cache configured - add litellm_settings.cache_settings')

def has_cache_settings(proxy_config: dict) -> bool:
    return bool((proxy_config.get('litellm_settings') or {}).get('cache_settings'))

r = httpx.get(f'{base}/cache/ping', headers=auth)
if r.status_code == 503 and 'Cache not initialized' in r.text:
    # configuration gap, not an outage - file a config fix instead of paging on-call
    mark_cache_unconfigured(env)

When it happens

Trigger: GET /cache/ping (with any valid virtual key) against a proxy whose config.yaml has no litellm_settings.cache_settings block.

Common situations: Cache health checks run against a proxy deployed without caching; Redis env vars (REDIS_HOST etc.) set but cache_settings never added to config; monitoring wired up before the cache feature itself.

Related errors

• Either 'REDIS_URL' or both 'REDIS_HOST' and 'REDIS_PORT' mus
• Either 'host' or 'url' must be specified for redis.
• REDIS_CLUSTER_NODES environment variable is not valid JSON.
• Both 'sentinel_nodes' and 'service_name' are required for Re
• 500

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