Troubleshooting

Start here:

fibers doctor

It runs nine checks in the order below and prints one line each. Three words appear in the status column. ok means done. missing means not done, with the cure on the line. waiting means it is waiting on you, or on something only time fixes, and says what. When a check cannot tell, it says waiting with the reason, never a confident missing.

The exit code is the summary: 0 when every check is ok, 1 when anything is missing or the launcher section below finds a problem, 2 when nothing is missing but something is waiting. fibers doctor --json prints the same facts as {checks, launcher, features, featuresConfig} for a script. features is each module’s on/off state and the file that decided it; featuresConfig names the machine and repo files and any error that made doctor exit 2.

The checks

claude-code-found

Is claude on PATH? If not, install Claude Code, or open a terminal where it is on PATH and run doctor again.

plugin-enabled-in-settings

Is the plugin enabled in your Claude Code settings file? A settings file that exists but does not parse as JSON is reported as waiting with the path: fix it by hand before anything else, because nothing here will edit a broken file for you. If the plugin is not enabled, the cure is the two slash commands from install the plugin.

plugin-installed

Is the plugin in Claude Code’s plugin cache? Enabled but not yet cached is waiting: Claude Code installs it at the next session start, or the cure installs it now. When the plugin is not found, the check is missing, with the install commands as the cure.

plugin-up-to-date

Does the installed version match what the marketplace advertises? Behind is missing, with the install command as the cure, since the plugin does not update itself. If the marketplace could not be read, or either side is not a version, the check says it cannot compare.

cli-signed-in

Is there a credential, and does the service accept it? No credential at ~/.fibers/credentials.json is missing; the cure is fibers login. A credential that is present but refused is missing with fibers login --force. A repo bound to a workspace that has no valid workspace token points you at fibers init instead, because workspace tokens come from init and personal ones from login.

repo-bound

Is this repo bound to a workspace? Run doctor from inside the repo you want on the board; outside a git repository it says so and waits. A binding file that only has a slug is waiting until fibers init writes the ids. A repo the service already knows by its git remote is ok with no file at all. Not bound anywhere is missing: fibers login once per machine, then fibers init in the repo root, which offers to create the workspace if it does not exist yet. On a machine with many checkouts, the worst one speaks and the others at its level are counted.

deployment-reachable

Did the deployment answer within the read budget? It scales to zero, so the first call after a quiet spell is usually just waking it: run doctor again. If it keeps failing, check the URL in ~/.fibers/deployment.json, or CONVEX_CLOUD_URL if you set one.

node-version

Is node on PATH and at or above the floor the plugin’s CLI needs? When Node is there, the plugin runs on it. From the release that ships the self-contained build, a machine without Node on macOS, Linux (glibc) or Windows x64 downloads that build once per plugin version, on first use, and runs it instead. This check does not know about the self-contained build yet, so it reports a missing Node either way. If fibers runs, you can ignore it. Where Node is needed, the cure is the Node download page.

sandbox-allows-fibers

Does Claude Code’s Bash sandbox let fibers through? The sandbox wraps the commands an agent runs, so fibers claim, fibers log and fibers turn run inside it while the plugin’s hooks do not. Turned on with nothing allowed, it refuses the call to your deployment and the write to ~/.fibers, so the event is neither sent nor queued. Off is ok. On is ok when sandbox.network.allowedDomains includes your deployment’s host and sandbox.filesystem.allowWrite includes ~/.fibers (in local mode only the folder is needed), or when sandbox.excludedCommands covers both ways agents type it, fibers and ~/.fibers/bin/fibers. Otherwise it is missing, and the cure is the lines to add under "sandbox". Doctor reads only ~/.claude/settings.json; if the sandbox is turned on somewhere else, a fibers command that it blocks prints the same advice once.

After the checks: which CLI ran

Doctor then says which copy of the CLI just ran and whether it is stale: the launcher at ~/.fibers/bin, the tree it points at, and any installed plugin copies behind the current release. --launcher forces that section when the launcher is absent.

Symptoms the checks do not name

• service unreachable (presence timeout) on the first command. The deployment was asleep and the client’s 1.5 second budget expired. Run the command again.
• A row never appears for a cloud session. Cloud sandboxes have no presence rail by design; they show in the work lane. Two service unreachable in a row there means the egress allow-list, and a 401 means the token. See cloud sessions.
• Two sessions show a clash line. They share a worktree, branch or ref. Nothing is adjudicated; the line is there so you can decide.