mlflow/mlflow · error · MlflowException

REQUEST_LIMIT_EXCEEDED

REQUEST_LIMIT_EXCEEDED

Error message

Completion iteration limit of {max_iterations} exceeded. This usually indicates the model is not powerful enough to effectively analyze the trace. Consider using a more intelligent/powerful model. In rare cases, for very complex traces where a large number of completion iterations might be required, you can increase the number of iterations by modifying the {MLFLOW_JUDGE_MAX_ITERATIONS.name} environment variable.

What it means

Judge tool-calling loops cap completion iterations (default via MLFLOW_JUDGE_MAX_ITERATIONS). If the model keeps calling tools without producing a final answer past the limit, _raise_iteration_limit_exceeded throws REQUEST_LIMIT_EXCEEDED with guidance to use a stronger model or raise the env var.

Source

Thrown at mlflow/genai/judges/utils/tool_calling_utils.py:36

_logger = logging.getLogger(__name__)

# Attribute used to tag an injected multimodal user-turn with the tool_call_id that
# produced it, so context-window pruning can drop it together with its tool-call pair.
# The user-turn has no tool_call_id of its own, so without this tag pruning would
# orphan it and break strict role alternation on overflow.
IMAGE_TURN_TOOL_CALL_ID_ATTR = "_mlflow_image_turn_tool_call_id"


def _raise_iteration_limit_exceeded(max_iterations: int) -> NoReturn:
    """Raise an exception when the agentic loop iteration limit is exceeded.

    Args:
        max_iterations: The maximum number of iterations that was exceeded.

    Raises:
        MlflowException: Always raises with REQUEST_LIMIT_EXCEEDED error code.
    """
    raise MlflowException(
        f"Completion iteration limit of {max_iterations} exceeded. "
        f"This usually indicates the model is not powerful enough to effectively "
        f"analyze the trace. Consider using a more intelligent/powerful model. "
        f"In rare cases, for very complex traces where a large number of completion "
        f"iterations might be required, you can increase the number of iterations by "
        f"modifying the {MLFLOW_JUDGE_MAX_ITERATIONS.name} environment variable.",
        error_code=REQUEST_LIMIT_EXCEEDED,
    )


def _process_tool_calls(
    tool_calls: list[ToolCall],
    trace: Trace | None,
) -> list[ChatMessage]:
    """
    Process tool calls and return tool response messages.

    Args:

View on GitHub (pinned to 6a27f2decc)

Solutions

Use a more capable judge model that converges to a final answer
Set MLFLOW_JUDGE_MAX_ITERATIONS to a higher value for complex traces
Simplify the judge's available tools or input trace to reduce required steps
Check for tool errors that make the model retry endlessly (fix the underlying tool failure)

Example fix

// before
# default iteration limit, weak model
evaluate(model="small-model:1", ...)
// after
import os
os.environ["MLFLOW_JUDGE_MAX_ITERATIONS"] = "20"
evaluate(model="databricks:/databricks-claude-sonnet-4", ...)

Defensive patterns

Strategy: retry

Validate before calling

import os
max_iters = int(os.environ.get("MLFLOW_JUDGE_MAX_ITERATIONS", "10"))
assert max_iters >= expected_iterations_for_trace_complexity()

Try / catch

try:
    out = judge.invoke(inputs)
except MlflowException as e:
    if "iteration limit" in str(e):
        os.environ["MLFLOW_JUDGE_MAX_ITERATIONS"] = "25"
        out = retry_with_stronger_model(inputs)
    else:
        raise

Prevention

Choose judge models known to converge quickly
Trim tools/traces to what the judge needs
Set MLFLOW_JUDGE_MAX_ITERATIONS explicitly for complex workloads

When it happens

Trigger: Running a Databricks agentic-loop judge, or litellm/openai tool-calling invocations, where the model loops on tool calls and never emits a final structured answer within max_iterations.

Common situations: Weak/small models that repeat the same tool call, overly complex traces requiring many steps, MLFLOW_JUDGE_MAX_ITERATIONS left at the low default for intricate inputs.

Related errors

AI-assisted analysis of mlflow/mlflow@6a27f2decc (2026-08-29). Data as JSON: /api/errors/34d83c210b4afc36. Report an issue: GitHub.