BerriAI/litellm · error · Exception

Unable to parse model, max fallback depth exceeded - receive

Error message

Unable to parse model, max fallback depth exceeded - received model: {model}

What it means

Raised by the recursive _can_object_call_model() when fallback_depth reaches DEFAULT_MAX_RECURSE_DEPTH (100, overridable via the DEFAULT_MAX_RECURSE_DEPTH env var). The function recurses through model lists and model-alias indirections to check access; hitting the cap means the model reference could not be resolved to a concrete model within 100 hops — practically always a self-referencing alias chain.

Source

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

) -> Literal[True]:
    """
    Checks if token can call a given model

    Args:
        - model: str
        - llm_router: Optional[Router]
        - models: List[str]
        - team_model_aliases: Optional[Dict[str, str]]
        - object_type: Literal["user", "team", "key", "org"]. We use the object type to raise the correct exception type

    Returns:
        - True: if token allowed to call model

    Raises:
        - Exception: If token not allowed to call model
    """
    if fallback_depth >= DEFAULT_MAX_RECURSE_DEPTH:
        raise Exception(f"Unable to parse model, max fallback depth exceeded - received model: {model}")
    if isinstance(model, list):
        for m in model:
            _can_object_call_model(
                model=m,
                llm_router=llm_router,
                models=models,
                team_model_aliases=team_model_aliases,
                team_id=team_id,
                object_type=object_type,
                fallback_depth=fallback_depth + 1,
            )
        return True

    potential_models: Final = [model]
    if model in litellm.model_alias_map:
        potential_models.append(litellm.model_alias_map[model])
    elif llm_router and model in llm_router.model_group_alias:
        _model: Final = llm_router._get_model_from_alias(model)

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Audit model_list and team_model_aliases in config.yaml for circular references — every alias must eventually resolve to a concrete deployment (litellm_params.model of a real provider model)
2. Rename the alias so it differs from any model/alias it points to; break A->B->A chains by pointing one hop at a concrete model
3. As a temporary workaround, raise the cap via DEFAULT_MAX_RECURSE_DEPTH env var — but a cycle is a config bug and should be fixed

Example fix

# before (cycle: alias points at itself)
model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o   # NOT the alias name
# after
model_list:
  - model_name: my-gpt4o
    litellm_params:
      model: openai/gpt-4o

def assert_alias_graph_acyclic(model_list: list[dict]) -> None:
    names = {m["model_name"] for m in model_list}
    targets = {m["model_name"]: m["litellm_params"]["model"] for m in model_list}
    for start in names:
        seen, cur = set(), start
        while cur in targets:
            if cur in seen:
                raise ValueError(f"model alias cycle at {cur}")
            seen.add(cur)
            cur = targets[cur]

try:
    allowed = _can_object_call_model(model, llm_router, models, ...)
except Exception as e:
    if "max fallback depth exceeded" in str(e):
        raise ValueError("Circular/over-nested model alias config") from e
    raise

When it happens

Trigger: A model alias in the router/team_model_aliases that resolves to itself or forms a cycle (alias A -> alias A, or A -> B -> A); deeply nested wildcard/list expansions in a team's models config passed as nested lists; passing a model value whose alias chain never terminates at a deployment.

Common situations: Configuring model_group aliases where an alias name equals its upstream model (litellm_params.model pointing at another alias that points back); copy-paste alias configs creating loops; upgrade changes in alias resolution exposing previously latent cycles.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• LLM Router not initialized. Ensure models added to proxy.
• bucket_name must be provided for GCS destination
• {most_recent_exception_str}. All fallback attempts failed. E
• Max recursion depth {max_depth} reached while reading image
• model param not passed in.

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