BerriAI/litellm · error · HTTPException

Max depth of {DEFAULT_MAX_RECURSE_DEPTH} exceeded while proc

Error message

Max depth of {DEFAULT_MAX_RECURSE_DEPTH} exceeded while processing model fields. Please check the model structure for excessive nesting.

What it means

_extract_fields_recursive guards against pathological model nesting (self-referential or deeply recursive schemas) when building guardrail UI field forms; exceeding DEFAULT_MAX_RECURSE_DEPTH aborts extraction.

Source

Thrown at litellm/proxy/guardrails/guardrail_endpoints.py:1811

    if field_default is not None and field_default is not ...:
        field_dict["default_value"] = field_default

    # Copy min, max, step from json_schema_extra for number/percentage inputs
    if field_json_schema_extra:
        for key in ("min", "max", "step", "default_value"):
            if key in field_json_schema_extra:
                field_dict[key] = field_json_schema_extra[key]

    return field_dict


def _extract_fields_recursive(
    model: type[BaseModel],
    depth: int = 0,
) -> dict[str, object]:
    # Check if we've exceeded the maximum recursion depth
    if depth > DEFAULT_MAX_RECURSE_DEPTH:
        raise HTTPException(
            status_code=400,
            detail=f"Max depth of {DEFAULT_MAX_RECURSE_DEPTH} exceeded while processing model fields. Please check the model structure for excessive nesting.",
        )

    fields: Final = {}

    for field_name, field in model.model_fields.items():
        field_annotation = field.annotation

        # Skip optional_params if it's not meaningfully overridden
        if _should_skip_optional_params(field_name=field_name, field_annotation=field_annotation):
            continue

        # Handle Optional types and get the actual type
        if field_annotation is None:
            continue

        field_annotation = _unwrap_optional_type(field_annotation=field_annotation)

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Reduce nesting depth in the model/request structure.
2. Check for recursive or self-referential structures in the payload.

Example fix

Flatten overly nested message/metadata fields before sending the request.

When it happens

Trigger: Thrown at litellm/proxy/guardrails/guardrail_endpoints.py:1811 when the library encounters an invalid state.

Common situations: Model fields are nested deeper than the maximum recursion depth.

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