BerriAI/litellm · error · ValueError

if object_id_jwt_field is set, role_mappings must also be se

Error message

if object_id_jwt_field is set, role_mappings must also be set. Needed to infer if the caller is a user or team.

What it means

Raised while parsing the general_settings JWT auth block when object_id_jwt_field is set (LiteLLM should treat the caller as a user or team identified by a JWT claim) but role_mappings is missing. Role mappings are the only mechanism to infer whether a caller is a user or a team, so object-id-based auth cannot function without them; config load fails immediately.

Source

Thrown at litellm/proxy/_types.py:4652

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

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Set role_mappings when object_id_jwt_field is set.

Example fix

role_mappings={...}

When it happens

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