Troubleshooting
When something is not working, start here. Two commands cover most of it: one reports your installation’s health, the other shows what is running.
Check installation health
Section titled “Check installation health”barry doctor reports installation health, adapter problems, and identity
configuration drift:
barry doctorThe output is similar to the following:
...PASS service:identities.identities: enabled, running and healthy...PASS service:mcp.server: enabled, running and healthy...Add --fix to repair what it safely can: migrate retired identity keys, fix
row drift, and install missing commands. Add --strict to exit non-zero when
any check fails, which is useful in a script.
See what is running
Section titled “See what is running”barry status shows every service, its port, and its health, plus stores and
schedules:
barry statusThe output is similar to the following:
... Services (32/45 running)... ● identities.identities 4902 running pid 896 · health ok...If a service needs attention, barry service logs <service> prints its log,
and barry service restart <service> restarts it. barry up starts the
enabled services if they are down.
Common problems
Section titled “Common problems”The install finished but barry is not found
Section titled “The install finished but barry is not found”Setup installs the barry command on your PATH and prints where. Open a new
shell so the change takes effect, or add the printed directory to your PATH.
A session does not start, or the agent is missing
Section titled “A session does not start, or the agent is missing”Barry drives the harness’s own command-line tool, so install that tool first.
Check the harness with barry adapter doctor. If you installed it after setup,
register it with barry adapter add and the adapter’s path in your Barry
checkout.
Barry runs the harness on the identity’s key for the model’s vendor, never on
your own sign-in, and refuses a session without one. Give the identity the
key with <identity> identity secret set ANTHROPIC_API_KEY --in keychain,
using the vendor’s variable name. Barry asks for the value at a masked prompt.
If you pointed the identity at a local model, pull it first, such as
ollama pull qwen3:4b. A local model needs no vendor key.
A tool the agent should have is missing
Section titled “A tool the agent should have is missing”Packing a bag does not grant its tools; a trait does. Start the session with
--traits <bag>, or add the trait to the identity’s defaults with
<identity> identity traits add <bag>. Confirm what a trait grants with
barry trait list. Empowering with traits covers this.
A bound did not stop the agent
Section titled “A bound did not stop the agent”Barry enforces a bound on the tools it serves. A harness’s own built-in tools
are a separate path: a bound takes them back by category, and how firmly that
holds depends on the harness and the session mode. Cursor cannot turn off a few
of its tools, and in Antigravity’s and Codex’s terminal modes, /hooks switches
Barry’s gate off. Check
enforcement coverage before
relying on a bound as a security boundary.
A secret is not loading
Section titled “A secret is not loading”Confirm the identity resolves its secrets with <identity> identity check. A
vault-backed secret needs the vault set up (sudo barry setup --system) and an
account assigned to the identity. Manage secrets covers the
whole path.
A store refuses to open after an update
Section titled “A store refuses to open after an update”A store stamped by a newer build than the one running refuses to open, to avoid
corrupting it. Move the instance onto a build at least as new. On a release,
run the newer release’s bin/barry upgrade. On a linked checkout,
barry upgrade refuses, so update the checkout instead. See
Upgrade and roll back Barry.
When none of that resolves it
Section titled “When none of that resolves it”Capture barry doctor --json and barry status --full, and see the
support guide
for channels and what to include.