BerriAI/litellm · error · ValueError

Plugin claim audience mismatch

Error message

Plugin claim audience mismatch

What it means

Plugin session-claim verification: the Fernet token decrypted and decoded successfully, but the claim's audience does not match the plugin making the request, so a token minted for one plugin is being replayed against another; verification raises ValueError.

Source

Thrown at litellm/proxy/plugin_routes.py:171

        "exp": int(time.time()) + _CLAIM_TTL_SECONDS,
    }
    return _plugin_fernet(plugin_name).encrypt(json.dumps(claim).encode()).decode()


def verify_plugin_session_claim(plugin_name: str, ciphertext: str) -> dict:
    """Verify and decode a plugin session claim.

    Raises ValueError if the HMAC is invalid, the audience is wrong, or
    the claim is expired.  Returns the decoded claim dict on success.
    """
    try:
        raw: Final = _plugin_fernet(plugin_name).decrypt(ciphertext.encode(), ttl=_CLAIM_TTL_SECONDS)
        claim: Final = json.loads(raw)
    except (InvalidToken, Exception) as exc:
        raise ValueError("Invalid, tampered, or expired plugin session claim") from exc

    if claim.get("plugin") != plugin_name:
        raise ValueError("Plugin claim audience mismatch")
    if int(claim.get("exp", 0)) < int(time.time()):
        raise ValueError("Plugin session claim expired")
    return claim


# ---------------------------------------------------------------------------
# Config
# ---------------------------------------------------------------------------
def register_plugins_from_config(general_settings: dict[str, object]) -> None:
    """Replace the plugin registry from general_settings.

    Replaces (not merges) so plugins removed from config are immediately
    unreachable without requiring a process restart.
    """
    raw: Final = general_settings.get("plugins")
    entries: Final[list[object]] = raw if isinstance(raw, list) else []
    new_registry: Final = {p.name: p for p in (PluginConfig.model_validate(entry) for entry in entries)}
    _plugin_registry.clear()

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Load the plugin through its registered UI route so the claim audience matches; do not reuse claims across plugins.

When it happens

Trigger: Thrown at litellm/proxy/plugin_routes.py:171 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/174ac9721808b5a3. Report an issue: GitHub.