A session will not start
What to do when a new session turns red straight away, a model is greyed out, a session sits on Starting, or it says Rate Limited.
Most sessions that refuse to start have one of four causes, and each has a quick fix. Find the message or status you see below.
"Claude Code isn't installed (or can't be found)"#
Claude sessions run on the Claude Code program, which lives on your computer separately from Yardmaster. When Yardmaster cannot find it, the session turns red with this message.
Open Settings > Connected Tools.
Find Claude Code CLI and click Install.
Start a new session. Yardmaster picks up the program straight away, with no restart.
If you installed Claude Code somewhere unusual, open Settings > System and type its location under Claude CLI Location, or click Detect. Leave the box empty to let Yardmaster find it.
A model is greyed out: "Needs Claude Code CLI ..."#
Some Claude models only run on a recent enough Claude Code. When yours is older, that model stays in the model picker but greyed out, with the reason under it (for example "Needs Claude Code CLI 2.1.280, this computer has 2.1.251"). An Inbox card with Open Connected Tools settings appears too.
Open Settings > Connected Tools and click Update on Claude Code CLI. A terminal window opens and runs the update.
When it finishes, switch back to Yardmaster. Coming back to the window re-runs the check, and the grey rows and the Inbox card clear on their own.
Or simply pick a different model: only the models your Claude Code cannot run are blocked. See Connected tools for more on updates.
The session stays on "Starting"#
A session normally starts within seconds. If it stays on Starting:
Check your internet connection. Sessions need it to reach Claude.
Check your sign-in. Open Settings > Accounts; if an account says it needs signing in, sign in again. See Connect your Claude account.
Just after opening Yardmaster, sessions from last time come back one at a time on purpose, so a few can sit on Starting for a minute or more. See Sessions come back after a crash or restart.
If a session is still on Starting after a minute or two, it turns red (Error). Send it a message to try again.
"Rate Limited"#
The session has reached your Claude plan's usage limit. You do not need to do anything: it waits (orange Rate Limited) and carries on by itself when the limit resets. If you added more than one account, Yardmaster quietly moves it to an account that still has room.
To see how close you are to a limit, see Know before you hit a usage limit. To add another account, see Connect your Claude account.
Still stuck?#
Open the red session and read its last message: it usually names the cause. If it does not, send the team a report with the bug icon in the toolbar; see Report a problem or ask for help.
If Yardmaster cannot read your Claude Code version at all, it blocks no models on purpose: taking away a model that might work would be worse.
A very new model with no recorded minimum can still be refused by an older Claude Code. The turn then turns red and names the version it needs, and Yardmaster blocks that model for the rest of the run.
Sessions on a remote computer (SSH) are checked against Claude Code on this computer, so a remote session reports a version problem at its first turn instead.
On a Mac, the update may ask for your password when Claude Code was installed with the standard Node installer; installs through nvm or Homebrew do not ask.
A turn refused for this reason is not retried automatically, because the same model on the same Claude Code is refused every time.
Related
- Start and manage sessionsA session is one conversation with an agent, working in one project. Start one, read its status, and pause, snooze or archive it.
- Install and update your toolsSee which programs Yardmaster and your agents rely on, such as Claude Code, Git and the GitHub CLI, and install or update them from one list.
- Know before you hit a usage limitUsage Forecast watches how fast you use your Claude plan and estimates how long your 5-hour and weekly limits will last.