xtekky/gpt4free · error · ToolLoopError

Tool loop detected: request contains {total_tool_calls} tool

Error message

Tool loop detected: request contains {total_tool_calls} tool calls (limit {GLOBAL_TOOL_CALL_LIMIT}). The assistant is stuck calling tools repeatedly. Stop calling tools and answer directly, or switch strategy (e.g. use read_file with an absolute path instead of search).

What it means

Error "Tool loop detected: request contains {total_tool_calls} tool calls (limit {GLOBAL_TOOL_CALL_LIMIT}). The assistant is stuck calling tools repeatedly. Stop calling tools and answer directly, or switch strategy (e.g. use read_file with an absolute path instead of search)." thrown in xtekky/gpt4free.

Source

Thrown at g4f/api/tool_loop_detection.py:171

        role = message.get("role")

        # Assistant message may carry tool_calls.
        if role == "assistant":
            tool_calls = message.get("tool_calls") or []
            if isinstance(tool_calls, list):
                for tc in tool_calls:
                    key = _tool_call_key(tc)
                    if key is None:
                        continue
                    total_tool_calls += 1
                    call_counts[key] = call_counts.get(key, 0) + 1
                    tc_id = tc.get("id") if isinstance(tc, dict) else None
                    if tc_id:
                        pending_calls[tc_id] = key

                    # Hard global cap.
                    if total_tool_calls > GLOBAL_TOOL_CALL_LIMIT:
                        raise ToolLoopError(
                            f"Tool loop detected: request contains {total_tool_calls} "
                            f"tool calls (limit {GLOBAL_TOOL_CALL_LIMIT}). The assistant "
                            f"is stuck calling tools repeatedly. Stop calling tools and "
                            f"answer directly, or switch strategy (e.g. use read_file "
                            f"with an absolute path instead of search).",
                            function_name=key[0],
                            arguments=key[1],
                            repeats=total_tool_calls,
                        )

                    # Per-query repeat cap.
                    if call_counts[key] > MAX_REPEATS_PER_QUERY:
                        raise ToolLoopError(
                            f"Tool loop detected: function '{key[0]}' was called "
                            f"{call_counts[key]} times with identical arguments "
                            f"({call_counts[key] - 1} retries, limit is "
                            f"{MAX_REPEATS_PER_QUERY - 1}). Stop repeating this call. "
                            f"Arguments: {key[1]}",

View on GitHub (pinned to 973504e177)

Solutions

1. Stop issuing tool calls and answer the user directly.
2. Change strategy, e.g. use read_file with an absolute path instead of repeated searches.

When it happens

Trigger: Thrown at g4f/api/tool_loop_detection.py:171 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of xtekky/gpt4free@973504e177 (2026-08-14). Data as JSON: /api/errors/9d6a323a19850623. Report an issue: GitHub.