Troubleshooting

What anypick doctor checks, what it will and will not repair, and how to read a failure.

Start with doctor

anypick doctor
anypick doctor claude          # narrow to one client or provider
anypick doctor --fix --dry-run
anypick doctor --fix -y

doctor inspects the AnyPick data directory, the SQLite database, saved accounts and gateways, file permissions, lock and PID files, running proxies, and any operation journal entry that did not finish.

What `--fix` may touch

--fix works from a hard allowlist. It can:

delete a stale lock file
delete a stale PID file
stop an orphaned proxy
delete a temporary client overlay left behind by run
repair permissions on AnyPick-owned paths
rebuild derived caches
complete an interrupted journal rollback

It will not switch accounts, install packages, touch native auth files, or change your bindings. Anything outside the allowlist is reported as manual only, with the suggestion printed next to it — the terminal UI shows the same split.

Reading exit codes

Code	Meaning	Usual cause
`1`	Operational failure	Unexpected runtime error during a command
`2`	Invalid usage	`use` without `--with` or `--current`, or a bad flag
`3`	Not found	Account, gateway, preset, or client name does not exist
`4`	Auth required	A login or API key is missing or expired
`5`	Capability conflict	The source cannot serve that client, or no binding exists
`6`	Health failure	A health check failed
`7`	Missing dependency	An external proxy binary, such as `kirolink`, is not installed
`8` / `9`	Import refused	Bad export envelope, or the archive is too large
`130`	Cancelled	You pressed Ctrl-C

Common situations

A client launches but ignores the source

Check what is actually in effect — a project binding in the current directory beats your global default:

anypick current claude

If a stale project binding is winning, anypick unlink claude removes it.

`run` exits 5 with no binding

There is no ephemeral, project, or global binding for that client. Set one:

anypick use claude --with grok/work

A proxy will not start

Look at the log, then at the port:

anypick proxy status
anypick proxy logs gemini -n 100
anypick proxy config gemini work -p 4131     # move it

If a proxy from an earlier session is holding the port, anypick proxy stop with no arguments stops every account proxy, including inactive ones.

The Gemini proxy rejects a model

An OAuth-only Gemini account can sign a client in but cannot drive the proxy, which needs GEMINI_API_KEY in the saved login’s .env. If both sign-ins exist, pin one while you diagnose:

anypick proxy config gemini work --oauth-source gemini-cli
anypick proxy config gemini work --oauth-source antigravity

The terminal UI marks this ◐ changed. It means the provider’s CLI wrote a new credential after AnyPick took its snapshot. Adopt the new one:

anypick account refresh codex

Proxies keep running after I close the UI

Closing the TUI does not change existing proxy processes. To stop everything:

anypick tray stop

The TUI starts a supervisor only when you explicitly press Shift+D or start it from the Tray runtime screen.

An activation failed halfway

Mutating activation steps are recorded in an operation journal with backup paths, so a failed activation restores the prior state — client config, native auth, and any proxy it started. If the process was killed before rollback could finish, anypick doctor --fix completes it.

Digging deeper

anypick --trace use claude --with grok/work    # name each step, no secrets
ANYPICK_DEBUG=1 anypick proxy status           # echo internal events to stderr
anypick doctor --json                          # machine-readable findings

--trace prints the activation plan step by step, which is usually enough to see which stage failed. Combine with --dry-run to see the plan without running it.