BerriAI/litellm · error · ProxyException

PKCE_CACHE_MISS

PKCE_CACHE_MISS

Error message

PKCE verifier for state '{state}' has an unrecognized format (type={type(cached_data).__name__}). The cached entry may be corrupt.

What it means

Logged (and surfaced) during SSO PKCE callback handling: the cached PKCE entry for 'state' exists but its type is not a recognized shape (not a dict/tuple carrying code_verifier), so the verifier cannot be extracted. Indicates cache corruption or an incompatible writer stored the entry; the stale entry is deleted.

Source

Thrown at litellm/proxy/management_endpoints/ui_sso.py:3777

                raise ProxyException(
                    message=(
                        f"PKCE verifier for state '{state}' was found in cache but "
                        f"has an empty or null code_verifier value — possible storage bug."
                    ),
                    type=ProxyErrorTypes.auth_error,
                    param="PKCE_CACHE_MISS",
                    code=status.HTTP_401_UNAUTHORIZED,
                )
            elif cached_data is not None:
                await SSOAuthenticationHandler._delete_pkce_verifier(cache_key)
                verbose_proxy_logger.error(
                    "PKCE verifier for state '%s' has an unrecognized format (type=%s); "
                    "treating as a cache miss. Investigate the cached value — it may be "
                    "a corrupt or stale entry.",
                    state,
                    type(cached_data).__name__,
                )
                raise ProxyException(
                    message=(
                        f"PKCE verifier for state '{state}' has an unrecognized format "
                        f"(type={type(cached_data).__name__}). The cached entry may be corrupt."
                    ),
                    type=ProxyErrorTypes.auth_error,
                    param="PKCE_CACHE_MISS",
                    code=status.HTTP_401_UNAUTHORIZED,
                )
            else:
                if redis_usage_cache is not None:
                    cause = (
                        "The authorization and callback were likely handled by different "
                        "instances — the verifier was stored on one pod but not found on another."
                    )
                else:
                    cause = (
                        "The verifier may have expired (TTL), been lost on a pod restart, "
                        "or the PKCE authorization step was never completed. "

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Restart the SSO login flow; if it persists, flush the corrupted cache entry (Redis/cache) for that state.

When it happens

Trigger: Thrown at litellm/proxy/management_endpoints/ui_sso.py:3777 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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