Docs / Troubleshooting

Troubleshooting

Start here when something isn't moving or won't start. Most problems come down to Claude Code not being found or signed in, or a task waiting on something it tells you about.

Why is my task waiting?

A task that isn't running always says why, on its work block and on its task page. The reason comes with the time it started and, where there is one, when it'll resume. Here's what each one means and what to do.

What it saysWhat it meansWhat to do
Waiting for approvalA plan or a ship is waiting at a gate you set.Open the decision card and choose Approve plan or Ship it, or Send back with a note. Change the gates in Settings → Autonomy & gates.
Needs youA question, or a failure the team can't fix alone.Read the card in the thread or in Needs you, then Answer or Retry. The card says what went wrong.
Waiting for PAIR-14Another task has to finish first. If that task is stuck too, its key is named here.Open the named task and sort that out; this one starts by itself afterwards. If you cancel the other task, this one drops it and carries on. Use Unblock to start anyway.
Waiting for a free slotThe project already has as many teammates working, or as many pieces of work in progress, as it's allowed at once.Nothing; it starts when one finishes. To run more at once, raise Parallel agents or Work in progress in Settings → Autonomy & gates.
Usage limit, resumes 3:40 PMYour Claude account reached its usage limit.Nothing; it resumes at the time shown. To keep going sooner, add a second Claude or Codex account in Settings → Accounts.
PausedThe project, or the whole app, is paused.Resume the project from its menu, or turn off Pause everything in the menu bar.
Budget reachedA daily or per-task limit you set in Usage & limits was reached.Daily limits reset at midnight. For a per-task limit, choose Raise limit or Stop here on the card. See Usage and limits.
Retrying at 3:12 PMA run failed for a passing reason, such as the network or a crash, and will try again.Nothing, usually. Press Retry to try now. If it keeps failing, it moves to Needs you.
QueuedIt's ready and next in line.Nothing; it starts in moments.

Waiting tasks are also checked in the background. A step that stops responding is restarted on its own, so a task never stays stuck without saying so.

Claude Code isn't found

ThreadGrid looks for claude in these places:

  • ~/.claude/local
  • ~/.local/bin
  • /opt/homebrew/bin
  • /usr/local/bin

If yours is somewhere else, run which claude in Terminal and paste the path into Claude Code location in Settings → App. Then press Check again in the first-launch check, or Run a test in Settings → App.

Claude says I'm not signed in

Open Terminal, run claude, and type /login. Then press Test Claude in ThreadGrid.

Everything stopped at once

That's usually a usage limit on your Claude plan. Every waiting task says when it resumes, and so does the engine status at the bottom of the sidebar. There's nothing to fix: work picks up by itself. If you've added more than one account, ThreadGrid has already switched; see Usage and limits.

A ship failed

If it failed before the merge, nothing changed: read the reason in Needs you, fix it (often a dirty base checkout or a merge conflict) and press Retry. If it failed after the merge, the change is already in your base branch and the team has opened an urgent fix task. See Shipping targets.

The checks keep failing

The team runs your project's check commands (tests, typecheck, lint) before anything ships. If they fail on your base branch too, every task will fail verify. Run them yourself in the project folder; fix them or ask the team to in a thread ("the tests on main are failing, please fix them first"). You can change the commands in Settings → Project.

Logs

ThreadGrid keeps logs in ~/Library/Application Support/ai.threadgrid.desktop/logs. Include them when you report a problem.

Still stuck?

Email [email protected] with what you expected, what happened and the logs.

Something unclear or out of date? Email [email protected].