BerriAI/litellm · error · HTTPException

Plugin '{plugin_name}' is not registered.

Error message

Plugin '{plugin_name}' is not registered.

What it means

Guard in the plugin auth-token endpoint: the requested plugin_name is not in the registered plugin allow-list, so no audience-scoped key exists for it and a claim would be minted for an unknown plugin.

Source

Thrown at litellm/proxy/plugin_routes.py:239

) -> dict:
    """Issue a short-lived, audience-scoped plugin session claim.

    The claim contains {user_id, user_role, plugin, exp}.  It does NOT
    contain the caller's litellm bearer token — a compromised plugin can
    only learn the caller's identity, not impersonate them against the proxy.

    Encrypted with a key derived from HMAC(LITELLM_SALT_KEY, plugin_name),
    so each plugin holds only its own key and cannot forge claims for others.

    Requires LITELLM_SALT_KEY to be set; returns 503 otherwise.
    """
    if not os.getenv("LITELLM_SALT_KEY"):
        raise HTTPException(
            status_code=503,
            detail="LITELLM_SALT_KEY is not configured; plugin iframe auth unavailable.",
        )
    if plugin_name not in _plugin_registry:
        raise HTTPException(status_code=404, detail=f"Plugin '{plugin_name}' is not registered.")
    user_id: Final = getattr(user_api_key_dict, "user_id", None)
    user_role: Final = getattr(user_api_key_dict, "user_role", None)
    return {"session_claim": issue_plugin_session_claim(plugin_name, user_id, user_role)}


@router.api_route(
    "/plugin-proxy/{plugin_name}/{path:path}",
    methods=["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD"],
    tags=["plugins"],
    include_in_schema=False,
)
async def plugin_proxy(
    plugin_name: str,
    path: str,
    request: Request,
    user_api_key_dict: UserAPIKeyAuth = Depends(user_api_key_auth),
) -> Response:
    """Authenticated reverse-proxy to a registered plugin backend.

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Register the plugin in the proxy plugin configuration before opening its route.
2. Check the plugin name for typos against the registered plugin list.

When it happens

Trigger: Thrown at litellm/proxy/plugin_routes.py:239 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/14a6679862fb1782. Report an issue: GitHub.