BerriAI/litellm · error · ValueError

scope_mappings must be set if enforce_scope_based_access is

Error message

scope_mappings must be set if enforce_scope_based_access is true.

What it means

Config validation for JWT auth: enforce_scope_based_access is enabled but scope_mappings is unset, so there would be no mapping from token scopes to roles/objects and enforcement could only ever deny.

Source

Thrown at litellm/proxy/_types.py:4657

            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
    updated_by: str


class SpecialManagementEndpointEnums(enum.Enum):
    DEFAULT_ORGANIZATION = "default_organization"


class TransformRequestBody(BaseModel):

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Set scope_mappings when enforce_scope_based_access is true.

Example fix

scope_mappings={'read': [...]}

When it happens

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