Common issues

Find the symptom, read the cause, apply the fix. Runner-specific failures have their own deeper page: runner troubleshooting.

Symptom	Most likely cause	Fix
Cannot sign in	The invitation link has already been used	Sign-in
The runner sits at “Waiting for approval”	Nobody has approved the code yet	Pairing
A run never leaves pending	No runner is connected, or none advertises the right coding agent	Runs
Agent features fail with “no runner connected”	The workspace is on the runner backend with nothing paired	Runs
An invitation email never arrived	It is in spam, or the link was already used	Invitations
Something spent no tokens and returned 402	Trial credits are exhausted	Credits

I cannot sign in

Use the address your invitation was sent to. Invitation links are single-use, so if yours has already been redeemed, ask whoever invited you to send another. See users and invitations.

The runner will not pair

Work through these in order. The full set of pairing failures is in runner troubleshooting.

1. Approve the code. The terminal prints a URL and a code. Open it, sign in if asked, and approve. The runner is waiting for a person, not for the network.
2. Approve in the right workspace. The code only exists in the workspace whose address you passed to --server.
3. Codes expire after ten minutes. Re-run the installer for a fresh one.
4. A name is already taken. Display names are unique within a workspace, and retiring a runner does not release its name. Re-run with --display-name something-else.
5. The machine cannot contain an agent. The install stops before pairing and says so. Run commandchain-runner doctor for the reason. This is not overridable: use a managed runner for that machine. See proving containment with doctor.

A run is stuck and never starts

A run that stays pending is waiting for somewhere to execute. In order of likelihood:

No runner is connected. The app says so under Settings, then AI Backend. Agent actions fail with HTTP 503 and the error key no_runner_available rather than silently falling back to a paid API.

curl -fsSL https://github.com/commandchain-ai/commandchain-runner-dist/releases/latest/download/install.sh \
  | sh -s -- --server https://your-commandchain

A runner is paired but reads offline. Runners are graded on how recently they reported in. Check sh install.sh --status on that machine, and see runner troubleshooting.

No runner has the right coding agent. A run dispatched for a tool that no connected machine has waits rather than running with the wrong one. The error names every runtime it tried and why each was passed over. Install the tool on that machine and restart the runner. See coding agents.

There is no coding-agent credential. The runner reaches the point of starting the agent with nothing to authenticate with. Capture your login from a machine you are signed in on:

commandchain-runner creds push --agent claude-code

The workspace is at its concurrency limit. A workspace runs a fixed number of runs at once, five by default. Later runs queue until one finishes. See limits.

An invitation email never arrived

Check spam first. Invitations are sent as soon as they are created, so a missing message is almost always a filtering problem rather than a failed send.

If it is not there, the invitation record still exists and its link still works. Whoever sent it can reopen the invite dialog, copy the link with the Copy button, and send it directly. Re-sending also works. See users and invitations.

A request returned 402

Trial credits are exhausted. The request stopped before calling a model, so nothing was spent and no partial work happened. The error key is trial_credits_exhausted.

Pair a runner, or connect your own AI credential. See trial credits.

Next steps

• Runner troubleshooting: every runner failure, in depth.
• FAQ: the questions before the symptoms.
• Get help: when none of this fits.