> ## Documentation Index
> Fetch the complete documentation index at: https://squad.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Fix an agent that is stuck or failing

> Find out why an agent does not reply or a run failed, and fix the cause.

Use this page when an agent does not reply, a run failed, or a mission stopped moving. Start at the Health screen, then find the message that you see and follow its fix.

## Start at the Health screen

The Health screen collects today's failed runs in one place. The other screens show only a short link to it:

* Home: "\[n] runs today may need a look; details in Health"
* Missions: "\[agent] hit a snag today; details in Health"
* An agent's profile: "\[n] runs today may need a look; details in Health", or a line about routine interruptions today

1. Select one of these links. The **Health** screen opens.
2. Read the sections on the screen.

| Section                   | What it means                                                                                                                                                                                                       |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **All clear**             | "No failed runs today, and no provider limits in effect."                                                                                                                                                           |
| **PROVIDER STATUS**       | Your AI provider is refusing calls because of rate limits. See [Rate limits](#rate-limits-and-fallback).                                                                                                            |
| **NEEDS A LOOK**          | Runs that failed today. Each card shows the agent, the error, **Technical details**, and **View in Runs →**.                                                                                                        |
| **ROUTINE INTERRUPTIONS** | Runs that were cut short, for example by a restart of the workspace computer. The screen says that they pick back up automatically, but Squad does not start them again. See [Interrupted runs](#interrupted-runs). |

For more about Health and Runs, see [See what your agents did](/docs/runs-and-health).

## Read the run detail

<Steps>
  <Step title="Open the run list">
    On a card in **NEEDS A LOOK**, select **View in Runs →**.
  </Step>

  <Step title="Open the run">
    Select the run. The run detail opens.
  </Step>

  <Step title="Read the label">
    Read the box at the top.
  </Step>
</Steps>

| Label                | What it means                                                                                                                           | What to do                                                 |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| **Interrupted**      | A restart of the workspace computer or a newer run cut the run short, or a short provider error stopped it and Squad already retried it | After a restart, see [Interrupted runs](#interrupted-runs) |
| **Presumed stopped** | The run stopped sending events and did not report an end. New activity corrects the row if the run is still working.                    | Wait. If nothing changes, ask the agent again              |
| **Superseded**       | A newer run on the same conversation replaced this run                                                                                  | Nothing                                                    |
| **Timed out**        | The run reached its time limit                                                                                                          | See [Timeouts](#timeouts)                                  |
| **Run failed**       | The run ended with an error. The error text is below the label                                                                          | Read the error, then find it on this page                  |

Open **Technical details** for the full error text. Give this text to support if you ask for help.

### Error texts in a run

The run detail shows a short sentence. The raw text is under **Technical details**. These sentences are common:

| Error text                                                                                         | What it means                                                                                                                        | What to do                                                                                                                             |
| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| "\[model] (the first model tried) failed: \[reason]. The \[n] fallbacks that followed failed too." | Your default model failed, and then every fallback model failed. The reason is the error of the default model.                       | Fix the reason for the default model, for example an expired AI connection. See [An expired AI connection](#an-expired-ai-connection). |
| "Stopped by the wedge watchdog: no progress signals for \[n] minutes"                              | The run showed no progress for too long, so Squad stopped it.                                                                        | Ask the agent to continue. See [Timeouts](#timeouts).                                                                                  |
| "Run was stopped during memory compaction … — the work up to that point is saved"                  | The run was stopped while the agent was shortening its working memory.                                                               | Ask the agent to continue.                                                                                                             |
| "Run was stopped (…)" with a time-out reason                                                       | The run reached its time limit.                                                                                                      | See [Timeouts](#timeouts).                                                                                                             |
| "The email service rejected the call (\[code]): \[reason]"                                         | A call to the email service failed. Other services show as "the integrations service", "the memory service", or "a backend service". | Read the reason. For email, see [Fix email problems](/docs/email-troubles). For apps, see [Connect apps](/docs/integrations#troubleshooting).    |

## Chat failure messages

When an agent cannot answer in chat, the chat shows one of these messages under your message.

| Message                                                                                                                                       | Cause                                                                                                               | Fix                                                                                                                                                    |
| --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| "Your AI connection expired. The agent can't reply until you reconnect it in Settings → AI Tokens."                                           | The sign-in or key for your AI provider is no longer valid.                                                         | Select **Reconnect in AI Tokens →** and connect the account again. Then select **Retry**. See [Choose models and manage AI accounts](/docs/ai-accounts).    |
| "The agent didn't reply — it may be busy or restarting. Retry in a moment."                                                                   | The agent is busy, or its workspace computer is restarting. A settings change also restarts the workspace computer. | Wait a minute, then select **Retry**.                                                                                                                  |
| "The connection dropped while the agent was replying. It may still be finishing the work — check its recent activity, or Retry to ask again." | The agent got your message, but the reply did not reach you.                                                        | Check the agent's recent activity first. Select **Retry** only if the agent did not do the work. A retry asks again and can start the same work twice. |
| "The workspace runtime restarted while handling this message, so it may not have been processed. Send it again if nothing arrived."           | The workspace computer restarted during the run.                                                                    | Check the chat and the agent's activity. Send the message again only if nothing arrived.                                                               |
| "No reply arrived — the agent's run ended without answering. Retry to resend."                                                                | No answer came within 15 minutes.                                                                                   | Select **Retry**.                                                                                                                                      |
| "No reply arrived. The group message's run ended without answering, so send it again to reach the group."                                     | The same, in a group chat. A group message has no **Retry**.                                                        | Send the message again.                                                                                                                                |
| "The agent run could not be started on the workspace runtime. Try again."                                                                     | The run did not start.                                                                                              | Select **Retry**. If it happens again, see [Ask your lead to check](#ask-your-lead-to-check).                                                          |
| "The run started, but its result could not be recorded. Check the replies above and Recent Activity before retrying."                         | The run started, but Squad did not record how it ended.                                                             | Read the replies above the message and the agent's recent activity. Retry only if the work is not done.                                                |
| "The run finished, but its completion could not be recorded. Check the replies above and Recent Activity before retrying."                    | The run finished, but Squad did not record the end.                                                                 | Read the replies first. The work is usually done.                                                                                                      |
| "Some replies may not have reached the dashboard (…). Check Recent Activity for the full run."                                                | Some replies from a finished run did not reach the chat.                                                            | Open the Live Feed or the agent's activity to see the full run.                                                                                        |

## An expired AI connection

When your AI connection expires, the dashboard tells you in more than one place:

* The chat shows "Your AI connection expired. Replies will fail until you reconnect." with **Reconnect →**.
* Missions can show "Nothing ran today; your AI connection expired." with **Reconnect in AI Tokens →**.
* On **AI Tokens**, the account shows a status such as **EXPIRED** or **LOGIN INVALID**.

Fix: open **Settings** > **AI Tokens** and reconnect the account. Runs that use an expired account fail until you reconnect it. Squad does not retry these runs for you.

## Rate limits and fallback

A rate limit means that your AI provider refuses calls for a time, because your plan reached its limit.

* On **AI Tokens**, an account that hit a limit recently shows **Rate-limited · cooling down**.
* After 3 or more rate-limit failures in a row, Health, Home, and Missions show "\[provider] is rate-limiting your agents." For the exact rule, see [Limits and defaults](/docs/limits-and-defaults#runs).

What happens next depends on your setup:

* With more than one account for a provider, Squad tries the accounts in the order on the provider card, highest first. Claude Code is different: it uses one account at a time and moves to the next account when the active one reaches its usage limit. **AI Tokens** then shows the new account as **IN USE**. A run that had not done any work yet runs once more on the new account. A run that had already started is not repeated. See [Limits and defaults](/docs/limits-and-defaults#runs).
* With fallback models in the **Model routing** card on **AI Tokens**, a run that fails or hits a rate limit moves to the next model in the list.
* With no fallback models, the card says "No fallbacks are set. When the default model fails, runs on it fail until it recovers."

The banner says that agents retry automatically. Squad does not retry runs that failed because of a rate limit. A failed chat reply needs your **Retry**. See [Which runs retry](#which-runs-retry-automatically).

Fix:

1. Wait for your provider's limit to reset.
2. To avoid the problem, add a second account or a fallback model. See [Choose models and manage AI accounts](/docs/ai-accounts).

## Timeouts

A run can stop for two time reasons:

* It reached its timeout. Agent Configuration has a **Default timeout**: "Maximum seconds any single agent run may take before it is stopped." A scheduled task has its own **Timeout (seconds)**. For the default values, see [Limits and defaults](/docs/limits-and-defaults#runs).
* It showed no progress for a long time. Squad stops a run that sends no progress signal, such as a tool call, for a set period. For the period, see [Limits and defaults](/docs/limits-and-defaults#runs).

To give a run more time:

<Steps>
  <Step title="Open the timed-out run">
    Open the run detail with the label **Timed out**.
  </Step>

  <Step title="Open Agent Configuration">
    Select **Raise the timeout →**. Agent Configuration opens for that agent.
  </Step>

  <Step title="Scheduled task runs">
    If the run came from a scheduled task, open that task under **Scheduled Tasks**. Type a larger number in **Timeout (seconds)**.
  </Step>

  <Step title="Other runs">
    For other runs, select the **Workspace defaults** tab. Type a larger number in **Default timeout**.
  </Step>

  <Step title="Save">
    Select **Save changes**.
  </Step>
</Steps>

The workspace computer restarts to apply the change, which interrupts runs in progress. For more about scheduled tasks, see [Schedule recurring work](/docs/scheduled).

## Interrupted runs

A restart of the workspace computer ends every run in progress. Settings changes and routine maintenance cause restarts. The run detail shows **Interrupted**.

The run detail and the Health screen say that the run picks back up automatically. Squad does not start the run again. Check the agent's work. If it is not done, ask the agent to continue.

```text Ask the agent theme={null}
Your last run was interrupted by a restart. Check what you finished, then continue the work.
```

## Which runs retry automatically

Do not expect every failed run to run again. Squad retries only these cases:

| Case                                                                                     | What Squad does                          |
| ---------------------------------------------------------------------------------------- | ---------------------------------------- |
| A scheduled run failed with a temporary provider error, for example an overloaded server | Squad runs it once more, 2 minutes later |
| A run fails or hits a rate limit and you set fallback models                             | The run moves to the next model          |

Squad does not retry these cases:

* An expired or invalid AI connection
* A usage limit or quota error from your provider
* A run where all models in the fallback list failed
* A chat reply that failed. Select **Retry** yourself.
* A manual run or a chat run that failed with a provider error
* A run that a restart interrupted

## A mission shows "Stuck for … · no progress"

Symptom: a mission card on Missions shows "Stuck for" a time, then "no progress".

Cause: the mission had no update for a long time. The agent can be waiting for your answer, or its runs can be failing.

Fix:

1. Open **My Tickets** and answer any open ticket for that mission. See [Answer tickets in My Tickets](/docs/tickets).
2. Check Health for failed runs of the agent.
3. Open the mission and ask the agent for a status update in the mission thread.

## An agent shows "Paused by you"

Symptom: the agent's profile shows "Paused by you" at the top, and its scheduled tasks do not run.

Cause: a paused agent does not start scheduled runs. It still answers chat, missions, and email, so a pause does not explain a missing chat reply.

Fix: select **Resume**. Before you do, read what Resume changes in [Add, change, and pause agents](/docs/agents).

If the profile shows "Needs attention" and a reason, read the reason and follow the fix on this page.

## A new agent does not answer yet

Symptom: your lead just added an agent. A group chat refuses it with "\[name] is still being set up and cannot join a group chat yet." A Telegram, Discord, or Slack bot refuses it with "That agent can’t answer chats yet — pick another."

Cause: a new agent needs about 2 minutes before it can work. See [Limits and defaults](/docs/limits-and-defaults#setup-and-account).

Fix: wait a few minutes, then try again. Until then, work that you send to the new agent can go to the lead instead.

## Ask your lead to check

Your lead agent can look at the problem from inside your workspace.

```text Ask your lead theme={null}
One of my agents looks stuck. Check its recent runs and missions, tell me what failed and why, and suggest a fix.
```

## Still stuck

Email [support@squad.so](mailto:support@squad.so). Give the agent's name, the time of the run from Runs, and the text from **Technical details**. See [Get help](/docs/getting-help).