BerriAI/litellm · error · Exception

User role is required for CLI JWT login

Error message

User role is required for CLI JWT login

What it means

Raised by the CLI JWT login token generator when user_info.user_role is None. This flow mints an encrypted JWT (expiry LITELLM_CLI_JWT_EXPIRATION_HOURS, default configurable) for CLI authentication and embeds the user's role; a NULL role means authorization decisions in the CLI cannot be made, so the Exception is thrown before any token is produced.

Source

Thrown at litellm/proxy/auth/auth_checks.py:2944

        Args:
            user_info: User information from the database
            team_id: Team ID for the user (optional, uses user's team if available)
            team_alias: Team alias for the selected team, if available
            team_models: Model allowlist granted by the selected team
            team_model_aliases: Team model aliases for the selected team

        Returns:
            Encrypted JWT token string
        """
        import secrets
        from datetime import timedelta

        from litellm.proxy.common_utils.encrypt_decrypt_utils import (
            encrypt_value_helper,
        )

        if user_info.user_role is None:
            raise Exception("User role is required for CLI JWT login")

        # Calculate expiration time (configurable via LITELLM_CLI_JWT_EXPIRATION_HOURS env var)
        expiration_time: Final = get_utc_datetime() + timedelta(hours=CLI_JWT_EXPIRATION_HOURS)

        # Format the expiration time as ISO 8601 string
        expires: Final = expiration_time.strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "+00:00"

        # Use provided team_id, or fall back to user's teams if available
        _team_id = team_id
        if _team_id is None and hasattr(user_info, "teams") and user_info.teams:
            # Use first team if user has teams
            _team_id = user_info.teams[0] if len(user_info.teams) > 0 else None

        session_token: Final = f"{CLI_SESSION_KEY_PREFIX}-{secrets.token_urlsafe(16)}"
        session_alias: Final = f"{CLI_SESSION_KEY_PREFIX}-{user_info.user_id}"

        valid_token: Final = UserAPIKeyAuth(
            token=session_token,

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Set the role on the user: POST /user/update {"user_id": "...", "user_role": "proxy_admin" | "internal_user" | "customer"}
2. Configure default_user_role in your SSO/JWT auth settings so future auto-created users get a role at first login
3. Retry the CLI login after the update

Example fix

curl -X POST http://localhost:4000/user/update \
  -H "Authorization: Bearer $MASTER_KEY" \
  -d '{"user_id": "user-7", "user_role": "internal_user"}'

assert user_info.user_role is not None, "CLI JWT login requires user_role to be set"

def user_has_role(user: LiteLLM_UserTable) -> bool:
    return user.user_role is not None

try:
    token = get_cli_jwt_auth_token(user_info)
except Exception as e:
    if "User role is required for CLI JWT login" in str(e):
        raise RuntimeError("Set user_role via /user/update before CLI login") from e
    raise

When it happens

Trigger: Invoking the CLI JWT login endpoint for a user whose DB row has no user_role (NULL) — commonly an auto-provisioned user from custom JWT/SSO auth with no default role, or a manually created user row.

Common situations: Users provisioned by SSO without default_user_role; DB rows created outside the API; environments where role assignment was skipped during onboarding automation.

Related errors

• User role is required for experimental UI login
• Invalid hash key. Hash key={hashed_token}. Decrypted token={
• Could not find `lite` on your PATH. Claude Code's apiKeyHelp
• No fresh LiteLLM login found for this proxy. Run `lite login
• Login did not produce a usable token; cannot start `lite up`

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