BerriAI/litellm · error · ValueError

user_allowed_roles must be provided if user_roles_jwt_field

Error message

user_allowed_roles must be provided if user_roles_jwt_field is set.

What it means

Raised while parsing the general_settings JWT auth block when user_roles_jwt_field is configured (so JWT role claims will be mapped to LiteLLM roles) but user_allowed_roles is absent. Without the allowed-roles list there is no way to decide which mapped roles may authenticate, so the config is rejected at startup rather than producing undefined auth behavior.

Source

Thrown at litellm/proxy/_types.py:4649

        object_id_jwt_field: Final = kwargs.get("object_id_jwt_field")
        role_mappings: Final = kwargs.get("role_mappings")
        scope_mappings: Final = kwargs.get("scope_mappings")
        enforce_scope_based_access: Final = kwargs.get("enforce_scope_based_access")
        custom_validate: Final = kwargs.get("custom_validate")

        if custom_validate is not None:
            fn: Final = get_instance_fn(custom_validate, config_file_path=config_file_path)
            validate_custom_validate_return_type(fn)
            kwargs["custom_validate"] = fn

        if invalid_keys:
            raise ValueError(
                f"Invalid arguments provided: {', '.join(invalid_keys)}. Allowed arguments are: {', '.join(allowed_keys)}."
            )
        if (user_roles_jwt_field is not None and user_allowed_roles is None) or (
            user_roles_jwt_field is None and user_allowed_roles is not None
        ):
            raise ValueError("user_allowed_roles must be provided if user_roles_jwt_field is set.")

        if object_id_jwt_field is not None and role_mappings is None:
            raise ValueError(
                "if object_id_jwt_field is set, role_mappings must also be set. Needed to infer if the caller is a user or team."
            )

        if scope_mappings is not None and not enforce_scope_based_access:
            raise ValueError("scope_mappings must be set if enforce_scope_based_access is true.")

        super().__init__(**kwargs)


class PrismaCompatibleUpdateDBModel(TypedDict, total=False):
    model_name: str
    litellm_params: str
    model_info: str
    blocked: bool
    updated_at: str

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Provide user_allowed_roles when user_roles_jwt_field is set.

Example fix

user_allowed_roles=['admin','user']

When it happens

Trigger: Thrown at litellm/proxy/_types.py:4649 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/086ad5655c54e407. Report an issue: GitHub.