Troubleshooting

Find the message or symptom you see, then follow the fix. For a problem on a computer, the first step is almost always the same: run commandchain-runner in a terminal on that computer, and follow what it shows. If the terminal says the command is not found or not recognized, fix that first: see “commandchain-runner is not found” under Installing, below.

Entries that apply to one system only start with its name, for example Windows:.

Account

The verification email does not arrive

Check your spam or junk folder. It can take a few minutes to arrive.
On the Check your email page, select Send a new code. It becomes available 60 seconds after the last code. Use the code from the newest email.
If you already have an account with that email, you get an email to sign in instead of a code. Sign in, or reset your password.

The verification code is not accepted

The page says “That code is wrong or has expired. Check the newest email, or send a new code.” Codes work for 1 hour. Check that you typed the code from the newest email, or select Send a new code.

The password is not accepted

A password needs at least 12 characters, with one lowercase letter, one uppercase letter, one number and one symbol. The form ticks off each rule as you type.

Too many attempts

The page says, for example, “Too many attempts from this network. Try again in 12 minutes.” Each network gets 10 attempts every 15 minutes, shared across signing in, creating an account, entering a verification code, sending a new code and resetting a password. Wait the number of minutes shown, then try again.

The page says “Sign-up is busy right now.” or “New accounts are paused right now. Try again later.” CommandChain is limiting new accounts for a while. Wait the time shown, or try again later.

Signing in sends you to Check your email

Your email is not confirmed yet. Enter the code from the newest email, or send a new one, to finish creating your account.

Installing

No coding agent found

The full message is “No coding agent found. Install Claude Code, Codex, GitHub Copilot, OpenCode or Cursor and sign in to it. CommandChain finds it automatically within 2 minutes.” You do not need to install CommandChain again. Run commandchain-runner in a terminal: it offers to install Claude Code or Codex and walks you through signing in. Or install an agent yourself, sign in to it once in a terminal, and wait. See Supported agents.

commandchain-runner in a terminal says “Step 1 of 2: install a coding agent” or “Sign in to a coding agent”, and does not connect the computer until you finish. This setup is required, because CommandChain cannot do any work without a signed-in agent.

To install, type the menu numbers and press Enter. If an install fails, the menu says why, for example “Codex did not install:” followed by the reason. Codex installs with npm, so install Node.js and npm first, or pick Claude Code.
To use GitHub Copilot, OpenCode or Cursor, install it yourself, then type r and press Enter.
If it says “The sign-in finished, but <agent> has no saved sign-in on this computer yet. Try again.”, or that the sign-in stopped before it finished, press Enter to sign in again. On a computer without a browser, type d for a Codex device code.
Press Ctrl+C to quit and come back later.

CommandChain runs in the terminal instead of the background

The installer prints why, then runs CommandChain in that terminal or window. It stops when you close it. The reasons:

macOS: “macOS runs background apps only for a user logged in to the desktop. Log in to this Mac’s desktop and run the installer again.”
Linux: “This computer has no systemd user service manager, so CommandChain cannot run in the background here.”
Linux: “Background apps are not available in this login. This happens after su or sudo, and in some SSH sessions.” Log in as yourself directly, as the message says, and run the installer again.
Windows: “This computer does not allow background apps for your account, so CommandChain will run in this window.”

See “Computers without background apps” in Keep the CommandChain app running.

Installed and paired, but not running

If the installer ran without a terminal it could use, it pairs the computer and stops there. It says “CommandChain is installed and this computer is paired.” and “CommandChain is not running, so this computer shows as offline in CommandChain.” Run commandchain-runner in a terminal on that computer to start it.

Installed, but not paired

The installer says “This computer is not paired yet, so CommandChain was installed but not started.” The code was not approved in time, or CommandChain could not be reached. Run the same install command again to get a new code, and approve it within 10 minutes. If the installer also says to check that the server is reachable, check this computer’s network.

`commandchain-runner` is not found

On macOS and Linux, the installer puts the program in ~/.local/bin. If that folder is not on your PATH, the installer warns that it “is not on your PATH, so the commands below use the full path.” Add the folder to your PATH, or use the full path it printed.

On Windows, open a new PowerShell window. The installer added its folder to your Path, and windows that were already open miss that change.

Windows: the installer asks you to run it as yourself

The installer says “Run this in PowerShell as the Windows user who will use CommandChain.” It was started as the Windows system account. Open PowerShell as yourself and run the install command again.

Windows: the installer needs a newer Windows

The installer says “CommandChain needs Windows 10 version 1809 or later.” Update Windows, then run the install command again.

Windows: the installer does not support this PC

The installer says “CommandChain does not support Windows on Arm yet.” or “CommandChain needs a 64-bit x64 Windows PC.” CommandChain runs on 64-bit x64 Windows only. Use another computer.

Windows: Smart App Control is on

The installer says “Smart App Control is on for this computer.” Smart App Control blocks programs that are not signed by a known publisher, and CommandChain is not signed yet, so it cannot run on that computer. Use another computer.

Windows: PowerShell is restricted by your organization

The installer says “PowerShell on this computer is restricted by your organization (Constrained Language mode)”. Your organization limits what PowerShell can run, so the installer cannot run. Ask your IT team.

Windows: Windows Security removed or blocked CommandChain

The installer says “Windows Security removed or blocked the CommandChain program.”, “Windows blocked CommandChain (Smart App Control or your organization’s app policy).”, or “The installed program does not run on this computer.”. Or the program is missing after an install. If Windows Security quarantined it, allow it in Windows Security’s Protection history, then run the install command again.

Connecting

No browser opened, or the computer has no screen

Open the link the terminal printed on any device where you are signed in. Or open Computers, select Connect computer and enter the code shown on that computer.

The terminal is waiting for approval

Approve the code on the Connect a computer page. Each code works for 10 minutes. If one runs out while the terminal is waiting, a new one appears there.

The code expired, was denied or was already approved

The page says “This code has expired.”, “This code was denied.” or “This code has already been approved.” For an expired or denied code, run the install command again on that computer, or commandchain-runner if CommandChain is already installed there, to get a new one. An approved code needs nothing more.

Connected in the terminal, but not on Computers

You may be signed in to a different account from the one that approved the computer. A computer belongs to the account that approved it.
The computer may not have checked in yet. Run commandchain-runner in a terminal on that computer, and follow what it shows. If it says it “has not reached” CommandChain since a given time, see the next problem.

Cannot reach CommandChain

The terminal shows ”! Cannot reach CommandChain. Retrying…”. The installer can also say CommandChain “has not reached” the server yet and “keeps trying”. The computer needs outbound HTTPS access to CommandChain. Check its network and any firewall or proxy. It reconnects by itself once it can.

CommandChain no longer accepts this computer

The terminal or log says “CommandChain no longer accepts this computer’s pairing.” This happens when the computer was removed in the CommandChain app. Run commandchain-runner in a terminal on that computer, and follow what it shows. In a terminal it asks: “Press Enter to pair this computer again, or Ctrl-C to stop.” Press Enter and approve the new code.

The same computer appears twice on Computers

Pairing a computer again creates a new entry. The old one stays Offline. Select Remove on its card. If the app says “This computer was connected in the last 5 minutes. Try again after it has been offline for 5 minutes.”, wait and try again.

Running

CommandChain is already running

The terminal says “CommandChain is already running on this computer (pid N). Run commandchain-runner to check on it.” Only one CommandChain runs per computer. Run commandchain-runner to see where it runs and whether it is connected.

CommandChain could not start in the background

The terminal says “CommandChain could not start in the background. See the log:” followed by a file. Open the log file the message names and look at its last lines. Log locations are in Keep the CommandChain app running. If the cause is not clear, see Get help.

An agent is missing from the computer’s card

The agent must be installed for your user and run from a terminal. CommandChain looks on your PATH and in the usual install locations. See Supported agents.
A newly installed agent appears within 2 minutes. Use the refresh control on Computers.
If it still does not appear, restart the CommandChain app (see Keep the CommandChain app running).

CommandChain uses each agent’s own sign-in. Sign in once in a terminal on that computer:

Claude Code and Codex: open the CLI and use its own sign-in.
GitHub Copilot: run copilot login.
OpenCode: run opencode auth login.
Cursor: run cursor-agent login.

A session shows Computer offline

The computer is off, asleep, or the CommandChain app on it is not running. Messages you send wait until it reconnects. Run commandchain-runner in a terminal on that computer, and follow what it shows.

A message shows a delivery warning

CommandChain could not confirm that the agent received the message. Review the conversation before you resend: resending could repeat work the agent already started. See Send messages and files.

The app asks you to update CommandChain on a computer

The app says “Notes need a newer version” or “Update CommandChain on this computer”. That computer runs an older version of the CommandChain app. CommandChain normally updates itself within a few hours of a release, once nothing is in progress. To update now, run commandchain-runner update on that computer. If automatic updates are off there, or the computer has been offline, that is the likely cause. See Update or uninstall.

CommandChain went back to an older version

A new version failed to start 3 times in a row, so CommandChain went back to the version you had before. Your sessions reconnect by themselves. It does not install that version automatically again; the next release installs as usual. If the problem keeps happening, get in touch and include the log. Log locations are in Keep the CommandChain app running.

Sessions briefly went offline and came back

CommandChain restarts after it installs an update, at a moment when nothing is in progress. Sessions reconnect by themselves. To choose when updates happen yourself, see Turn automatic updates off.

Device notifications are unavailable

Open Notification settings from the account menu or the Notifications page to check your device.

On iPhone and iPad, notifications work only from the Home Screen app. Add CommandChain to your Home Screen and open it from there.
If notifications are blocked, allow them in your browser or device settings, then reopen the page.
If this browser or the server cannot send notifications, the page explains this. You can still review activity in your Notifications list.

Too many devices registered

The app says “You have 20 devices registered, the most allowed.” Each browser or Home Screen app where you send messages or turn on notifications counts as one device. The app has no control for removing a device yet, so get in touch and we can help.

Claude Code in your terminal does not connect

Run commandchain-runner claude-integration status to check that the CommandChain plugin is installed.
If you started Claude Code before the plugin was installed, restart Claude Code or run /reload-plugins in it.
If a found session says the integration is loaded but its idle-message monitor is not connected, check that CommandChain is still running on this computer.
If you start Claude Code with your own CLAUDE_CONFIG_DIR, the plugin is not set up in that folder, so that Claude Code does not connect. See Claude Code with a custom configuration folder.
Windows: “Connecting to Claude Code sessions open in a terminal is not available on Windows yet. Sessions started from CommandChain work as usual.”

See Connect Claude Code in your terminal.

A server address is refused

commandchain-runner accepts an https:// address for any server, and plain http:// only for this computer (localhost, 127.0.0.1 or [::1]). An address with a user name, password, query or fragment is refused too.