Errors and Troubleshooting

Troubleshooting entry point for CrabCode startup, install, PATH, login, App Server, plugins, automations, and browser issues.

Locate the failing layer first

CrabCode combines the TUI, GUI, App Server, cron daemon, plugins, and browser automation. Start by identifying the layer.

Symptom	Layer	Start here
Terminal says `crabcode: command not found`	Install / PATH	Install, PATH, and uninstall
`crabcode --version` still shows an old version	PATH order / stale install	Install, PATH, and uninstall
`doctor` reports missing `git` / `gh`	Local dependencies	CLI reference
Desktop shows account service unavailable	App Server / account state	GUI quickstart
Work mode has no capability cards	Plugins / skills	GUI Work Mode, Plugins and skills
Automations says daemon unavailable	cron daemon	Automations
Browser task cannot use login state	Chrome extension / browser backend	Browser automation
Model quota or availability errors	Model gateway / entitlement	Costs, Model routing

Install and PATH

The most common issue is a successful install that the current shell cannot find.

bash

command -v crabcode
crabcode --version
command -v crabcode
crabcode --version

If nothing prints, check the real program directories:

bash

ls -la "$HOME/.crabcode/bin/crabcode" "$HOME/.local/share/crabcode/crabcode" 2>/dev/null
ls -la "$HOME/.crabcode/bin/crabcode" "$HOME/.local/share/crabcode/crabcode" 2>/dev/null

Then add the actual directory to PATH. See Install, PATH, and uninstall for zsh, bash, fish, and Windows steps.

GUI and App Server

Every real desktop data page talks to the local App Server. If Desktop shows account service unavailable, an empty project list, or an infinite loading state:

Click Retry in the GUI.
Quit and reopen Desktop.
Run crabcode doctor in a terminal.
Confirm the TUI can launch; if the TUI cannot open, fix install/PATH first.

Desktop package formats and platforms are listed on /downloads. Public GUI packages currently cover macOS .dmg and Windows x64 setup.exe; Linux currently uses the TUI.

Work mode

Work-mode issues are usually about workflow attribution or missing plugin capabilities, not lost sessions.

Symptom	Fix
Preset workflows appear but no capability cards	Install or enable the official backing plugin
Clicking finance/legal/office opens Plugins	Normal install guidance; install the plugin and return to Work
Custom skill exists but Custom workflow is missing	Enable the skill; if you unmounted Custom before, re-mount it with `+`
Chat appears under unattributed workflow chats	Create from a workflow row to auto-assign it

See GUI Work Mode.

Automations and cron

Automations are executed by the local crabcode-cron daemon. If the GUI Automations page reports unavailable:

bash

crabcode cron status
crabcode cron list --json
crabcode cron status
crabcode cron list --json

If CRABCODE_DISABLE_CRON=1 is set, cron is disabled. See Automations and CLI reference.

Browser automation

Browser tasks have two backends:

Mode	Check
Built-in browser mode (default, `crabcode-browser`)	Whether the release bundles `crabcode-browser` (or `CRABCODE_BROWSER_BINARY` points to the executable) and risky actions are allowed (`CRABCODE_BROWSER_ALLOW_RISKY`)
Chrome extension mode	Extension is loaded, native host is written, `CRABCODE_CHROME_EXTENSION_ID` is correct

Use Chrome extension mode when a task needs your real browser login state. See Browser automation and browser extension setup.

When to inspect logs

Start the TUI with debug logs:

bash

crabcode --debug
crabcode --debug

Debug logs are written under CrabCode's config directory by default; override with CRABCODE_DEBUG_LOGS_DIR. Before debugging, confirm the log directory exists and your user can write to it.