Cline "hit repeated tool call failures": causes and fixes

You gave a task, Cline worked a couple of steps and stopped with "Cline hit repeated tool call failures. Try guiding it with a new prompt." This is not a gateway error and not an API status code: the agent stopped itself because several tool calls in a row ended badly. Below is what usually stands behind it and the order in which to check.

A note on sources. The Cline documentation (docs.cline.bot) does not contain this message: its troubleshooting section covers networking and proxies. The mechanism described below comes from the source code of the cline/cline repository and from practical checks, so details may differ in your version.

What the message means

Cline works in a loop: it sends the model the context, gets back a tool call (read a file, run a command, write an edit), executes it and returns the result. The source code has a counter of consecutive "mistakes" of three kinds: an API request error, an invalid tool call, and a failure while executing a tool. When the counter reaches an internal limit (the exact value depends on the version), Cline stops and asks for new guidance. The task state is preserved. There is also a separate loop guard that triggers when the agent calls the same tool with the same arguments again and again.

The consequence: there are three different groups of causes, and you need to find which one is yours.

Checking order

1. Rule out connection problems

The first group is ordinary API errors that Cline counts as failed steps. Check the key and address with a direct request that bypasses Cline:

curl https://api.zukko.pro/v1/chat/completions \
  -H "Authorization: Bearer fetch_your_key" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5-5","messages":[{"role":"user","content":"ping"}]}'

If an error comes back, that is the cause. Typical Zukko ones: 401 (wrong key), 402 (not enough balance), 404 model_not_found (typo in the model id), 429 (the key's daily or monthly limit is reached, or a restriction at the model provider), 503 (provider unavailable or model switched off, model_disabled). GET /v1/models returns the current ids.

A separate word on the address. In OpenAI Compatible mode the Base URL must be https://api.zukko.pro/v1, and recent Cline versions use it exactly as typed, without silently adding /v1. An address without the suffix gives a 404 on every request, and the loop stops after a few steps. More on the suffix: Base URL with or without /v1↗.

2. Check the context size

The second group is a context that has grown. Every agent step adds read files and command output to the history. As the history nears the model's window, requests begin to fail with an overflow error, and if the model settings state a wrong window, Cline may compress the history at the wrong moment.

What to do:

• in the OpenAI Compatible settings check the context window field: per the Zukko table Claude and GPT models have 1M tokens, GLM 128K, Grok 256K;
• run /smol to compress the current task's history, or /newtask to start a clean task with a short summary (both slash commands are described in the Cline documentation);
• do not attach whole directories to a message: name specific files.

More on the overflow error in context_length_exceeded↗.

3. Change the model or check its compatibility

The third group is the most common in discussions: the model formats tool calls poorly. Cline expects a strictly defined call structure from the model. If the model replies in plain text instead of a call, mixes up arguments or cuts the call off halfway, the step counts as failed. A cut-off can also come from too small an output token limit (OpenAI Compatible has a Max Output Tokens field).

What to do: switch to another model from the table and repeat the same task. We will not claim which model "handles tools better"; test on your own tasks. For reference, prices (as of October 18, 2026, input / output per 1M tokens) and the Artificial Analysis intelligence index:

A cheap model with a short window suits simple edits, but on a multi-step task with a large context it hits the limit sooner. If failures began only on long tasks, look at step 2 first rather than changing the model.

4. Check the rules

The fourth group is instructions that get in the agent's way. A rule like "answer in text only, do not run commands" or a long file of contradictory requirements can push the model toward replies without a tool call. Open the Cline rules panel and switch all rules off with the toggles, then repeat the task. If the failure is gone, switch rules back on one by one. A good rule is short, does not contradict the others and does not forbid what the agent needs to complete the task.

5. Rephrase the task

The message itself advises giving new guidance, and that works. Instead of "fix everything" give one step with a file name and the expected result. If the agent is stuck on one command, say plainly what is not working and which path to take.

What a failed loop costs

While the agent spins, it is billed as usual: every attempt sends the whole accumulated context. Say the context is 150,000 tokens and there are ten failed attempts in a row: 150,000 × 10 = 1,500,000 input tokens, ignoring cache. At input prices per 1M:

• deepseek-v4.1-flash ($0.013): 1.5 × 0.013 = $0.0195;
• gpt-6.1-sol ($0.27): 1.5 × 0.27 = $0.405;
• claude-sonnet-5-5 ($0.4): 1.5 × 0.4 = $0.60;
• claude-opus-5-5 ($0.8): 1.5 × 0.8 = $1.20.

The sums are not catastrophic, but if you leave automatic mode unattended, the loop repeats. Insurance: a daily and monthly limit on the key in the dashboard and a restricted list of allowed models. How to set this up is in the article on protecting against a looping agent↗. General Cline setup with Zukko is in the VS Code extensions docs↗.

FAQ

Is this a Zukko gateway error?

No. Cline itself produces the message after several failed steps in a row. The cause may be on the API side (an error code in the request log), or in the model, the context or the rules.

Will the task progress be lost?

Cline preserves the task state, and in the source the stop comes with advice to send a new prompt to continue. Keeping a git commit before risky edits is still worthwhile.

Will simply repeating the request help?

Sometimes, if the failure was temporary (a 429 or 503 from the provider). If the cause is context, rules or the model, a repeat leads to the same result and burns tokens.

How do I find out what exactly failed?

Make a direct curl request as shown above: the status code and body show whether the API is at fault. If curl answers normally, look for the cause in the model, context or rules (steps 2-4). You can cross-check spending in the Usage section of the dashboard.

If you need a key to test another model, create one in the Zukko dashboard and connect it in Cline following the instructions.