{"record":{"id":"34d83c210b4afc36","repo":"mlflow/mlflow","slug":"request-limit-exceeded","errorCode":"REQUEST_LIMIT_EXCEEDED","errorMessage":"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.","messagePattern":"Completion iteration limit of (.+?) 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 (.+?) environment variable\\.","errorType":"error_code","errorClass":"MlflowException","httpStatus":null,"severity":"error","filePath":"mlflow/genai/judges/utils/tool_calling_utils.py","lineNumber":36,"sourceCode":"_logger = logging.getLogger(__name__)\n\n# Attribute used to tag an injected multimodal user-turn with the tool_call_id that\n# produced it, so context-window pruning can drop it together with its tool-call pair.\n# The user-turn has no tool_call_id of its own, so without this tag pruning would\n# orphan it and break strict role alternation on overflow.\nIMAGE_TURN_TOOL_CALL_ID_ATTR = \"_mlflow_image_turn_tool_call_id\"\n\n\ndef _raise_iteration_limit_exceeded(max_iterations: int) -> NoReturn:\n    \"\"\"Raise an exception when the agentic loop iteration limit is exceeded.\n\n    Args:\n        max_iterations: The maximum number of iterations that was exceeded.\n\n    Raises:\n        MlflowException: Always raises with REQUEST_LIMIT_EXCEEDED error code.\n    \"\"\"\n    raise MlflowException(\n        f\"Completion iteration limit of {max_iterations} exceeded. \"\n        f\"This usually indicates the model is not powerful enough to effectively \"\n        f\"analyze the trace. Consider using a more intelligent/powerful model. \"\n        f\"In rare cases, for very complex traces where a large number of completion \"\n        f\"iterations might be required, you can increase the number of iterations by \"\n        f\"modifying the {MLFLOW_JUDGE_MAX_ITERATIONS.name} environment variable.\",\n        error_code=REQUEST_LIMIT_EXCEEDED,\n    )\n\n\ndef _process_tool_calls(\n    tool_calls: list[ToolCall],\n    trace: Trace | None,\n) -> list[ChatMessage]:\n    \"\"\"\n    Process tool calls and return tool response messages.\n\n    Args:","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/mlflow/mlflow/blob/6a27f2decc0b76eb1b54af31849784addb357dbc/mlflow/genai/judges/utils/tool_calling_utils.py#L18-L54","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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)"],"exampleFix":"// before\n# default iteration limit, weak model\nevaluate(model=\"small-model:1\", ...)\n// after\nimport os\nos.environ[\"MLFLOW_JUDGE_MAX_ITERATIONS\"] = \"20\"\nevaluate(model=\"databricks:/databricks-claude-sonnet-4\", ...)","handlingStrategy":"retry","validationCode":"import os\nmax_iters = int(os.environ.get(\"MLFLOW_JUDGE_MAX_ITERATIONS\", \"10\"))\nassert max_iters >= expected_iterations_for_trace_complexity()","typeGuard":null,"tryCatchPattern":"try:\n    out = judge.invoke(inputs)\nexcept MlflowException as e:\n    if \"iteration limit\" in str(e):\n        os.environ[\"MLFLOW_JUDGE_MAX_ITERATIONS\"] = \"25\"\n        out = retry_with_stronger_model(inputs)\n    else:\n        raise","preventionTips":["Choose judge models known to converge quickly","Trim tools/traces to what the judge needs","Set MLFLOW_JUDGE_MAX_ITERATIONS explicitly for complex workloads"],"tags":["mlflow","judge","iteration-limit","tool-calling"],"backgroundTag":"iteration-limit-exceeded","analyzedSha":"6a27f2decc0b76eb1b54af31849784addb357dbc","analyzedAt":"2026-08-29T20:54:51.419Z","schemaVersion":2},"datasetVersion":"2026-08-29T22:17:34.462Z"}