Troubleshooting
Common issues and how to fix them. If something here doesn’t help, open an issue on GitHub or ask in Discord .
Most investigations start with one of these:
shep status --logs 100 # is the daemon up? last 100 lines of its log
shep ps # the daemon and every agent process Shep is running
shep feat status <id> # what one feature's agent is doing, and why
shep fleet status # running, queued, waiting on you, failed — and the queue stateAdd --debug (or --log-level debug) to any command for more output.
Setup
command not found: shep
Either Shep isn’t installed, or your global npm bin isn’t on your PATH.
npm i -g @shepai/cli
which shep
npm prefix -g # its bin/ folder should be on your PATHIf you used npx @shepai/cli, there’s no globally installed binary — keep using npx, or install globally.
Node.js 22+ required
Update Node.js. The easiest way is nvm:
nvm install 22
nvm use 22better-sqlite3 native module could not be loaded
Shep’s database driver is a native module. It breaks when its binary is missing or was built for a different Node version — typically right after a Node upgrade. Shep prints these steps; try them in order:
npm rebuild -g better-sqlite3
npm install -g @shepai/cli --foreground-scriptsIf it still fails, install a compiler toolchain (macOS: xcode-select --install; Linux: build-essential and python3; Windows: Visual Studio Build Tools), then reinstall.
gh: command not found
Install GitHub CLI from cli.github.com , then:
gh auth login
gh auth statusAgent not detected
Make sure the agent’s binary is on your PATH. Note that Cursor’s agent is cursor-agent, not cursor:
which claude # Claude Code
which kimi # Kimi Code
which codex # Codex CLI
which copilot # Copilot CLI
which cursor-agent # Cursor CLI
which gemini # Gemini CLI
which cline # Clineshep tools list shows which tools Shep can find, and shep install <tool> installs one (--how prints the instructions instead). In the web UI, the setup screen and Settings → Agent show the install or login command for the selected agent.
Then select it again: shep settings agent --agent <type> --auth session, or in Settings → Agent.
Daemon
Port 4050 already in use
You don’t need to do anything: if 4050 is taken, Shep starts on the next free port and prints the URL. To choose a port yourself:
shep start --port 4051
shep restart --port 4051 # if it's already runningshep status says “not running”
Start the daemon:
shep startIf that fails, read the daemon log:
shep status --logs 100 # last 100 lines
shep status -f # follow itThe log itself is ~/.shep/daemon.log (the previous one is daemon.log.old). Agent worker logs live in ~/.shep/logs/; clear old ones with shep logs prune --older-than 7d --yes.
shep stop doesn’t actually stop it
shep stop --force
shep ps # check nothing is leftThen shep start again.
I need the web UI in the foreground
shep ui runs the web server in the current terminal instead of as a background daemon — useful for watching its output. Use --port to pick a port and --no-open to skip opening the browser. Stop it with Ctrl+C.
Authentication
Agent says “not authenticated”
With session auth, Shep reuses the agent’s own login. Check that the agent works on its own:
claude --version # or kimi, codex, copilot, cursor-agent, gemini, clineIf that fails, sign in to the agent itself, then try again. For OpenRouter or Together AI, re-enter the API key with shep settings agent --agent openrouter --auth token --token <key> or in Settings → Agent.
gh says you’re authenticated but pushes fail
Check you’re logged in as the right account and have push access:
gh auth status
gh repo view --json viewerPermissionIf permission is READ, you can’t push. Get push access, or create the feature with --remote <owner/repo> — Shep forks the repo and opens the PR upstream.
Features
A feature stays Pending
It’s waiting for a slot. Either you created it with --pending, or you’ve set a parallel limit and that many features are already running. Queued features start in order as slots free up.
shep fleet status # how many are running and queued
shep feat start <id> # start a --pending feature
shep feat start <id> --force # start now, ignoring the limit
shep settings workflow --max-parallel 0 # remove the limitNothing new starts — the queue is paused
If someone ran shep fleet pause, new features are parked (running agents continue). shep fleet status, the fleet bar on the Control Center and a banner in shep tui all show queue paused with the reason. Resume with:
shep fleet resume…or the Resume button on the fleet bar, or u in shep tui.
The circuit breaker tripped
When many runs fail within the last 15 minutes (4 failures in a row, or more than 25% of completed runs), Shep reports that the circuit breaker tripped — in shep fleet status, the fleet bar and shep tui. It’s a warning that something systemic is wrong: an expired agent login, a broken main, CI down. Shep does not pause the queue for you. Find the cause first:
shep fleet triage # what needs a human decision
shep feat status <id> # why a given run failedPause new work with shep fleet pause --reason "…" while you fix it. Once fixed, shep fleet resume acknowledges the trip and shep fleet retry --failed restarts the failed runs.
A feature seems stuck
First ask Shep what’s going on:
shep feat status <id>It explains the agent’s state — working, needs you, waiting, done or failed — and the reason, such as waiting at an approval gate, a question for you, queued for capacity, or the process died. Then:
- Needs you: approve or reject the gate (
shep feat approve <id>/shep feat reject <id> --reason "…"), or answer the question in the web UI orshep tui. - Waiting / queued: see the two entries above.
- Process died or failed:
shep feat resume <id>.
To find stuck agent processes, run shep ps (add --all to include exited runs, -w to watch). Stop one with shep ps stop <id> — it takes a run ID, a feature ID or a prefix of either; add --force if it won’t stop.
Agent gets stuck in a loop
Stop it, then point it in the right direction or roll back:
shep ps stop <id>
shep feat checkpoints <id> # list the snapshot after each step
shep feat restore <id> <step> # roll the worktree back to one
shep feat resume <id>If it’s waiting at an approval gate, reject with guidance instead: shep feat reject <id> --reason "focus only on the controller".
Worktree directory missing
If you deleted a worktree by hand, Shep can’t recreate it. Delete the feature and start over:
shep feat del <id> --no-close-pr--no-close-pr keeps the PR open; by default shep feat del also deletes the local and remote branches and closes the PR.
”Branch already exists”
You already have a branch with the same name. Delete it, or adopt it as a feature instead:
shep feat adopt feat/your-feature-slug # track the existing branch as a feature
git branch -D feat/your-feature-slug # or delete it locally
git push origin --delete feat/your-feature-slug # and remotely if needednpm install fails inside a feature
Some agents sandbox network access. Allow the package registry’s hosts in your agent’s own settings.
CI
CI never starts
Shep watches GitHub Actions only, and only when the feature pushes (push or PR on). Make sure the repo has workflows under .github/workflows/ and that gh can see them. Trigger a run from the PR to confirm.
Auto-fix loops without converging
After the configured number of attempts (3 by default, Settings → CI), the run fails. Read the agent’s last commit and the failing CI logs together — usually the agent is misreading the error. Then resume with more guidance, or fix it yourself in the worktree:
shep feat logs <id>
shep feat resume <id>
shep ide <id> # open the worktree and fix it by handCommands and flags
”shep <command> is turned off”
That command belongs to a feature flag that’s off. The message names the command to run:
shep settings flags # every flag, its state and default
shep settings flags enable <flag>See Feature flags.
shep tui exits immediately
The terminal console needs an interactive terminal. In scripts, CI or a pipe, use shep feat ls, shep feat status <id> --json or shep ps --json instead.
Chat won’t start another session
The number of live chat sessions is capped (Settings → Chat → Max concurrent sessions). Close an idle chat or raise the cap. Idle sessions also stop on their own after the auto-timeout.
Usage metrics
How do I check or turn off usage metrics?
shep telemetry status # on or off, and what's queued
shep telemetry show # exactly what would be sent
shep telemetry off # turn it off and delete queued eventsDO_NOT_TRACK=1 or SHEP_TELEMETRY_DISABLED=1 force it off for that environment, and it’s always off when CI is set. See Usage metrics & privacy.
I turned it on but status still says off
An environment override wins over your setting. Check for DO_NOT_TRACK, SHEP_TELEMETRY_DISABLED or CI in your shell environment.
Dashboard
Dashboard won’t open
shep statusIf the daemon is running, open the URL it prints (usually localhost:4050 ). If not, shep start.
Dashboard loads but is blank
Hard-refresh (Cmd/Ctrl + Shift + R) to bypass cached assets. If still blank:
shep restartResetting everything
If Shep is in a state you can’t fix, start over:
shep stop
rm -rf ~/.shep
npm uninstall -g @shepai/cli
npm i -g @shepai/cli
shep # first-run setup opens in the browser againrm -rf ~/.shep deletes all settings and history and every worktree under ~/.shep/repos/ and every app under ~/.shep/projects/. Push anything you want to keep first. Branches and PRs on your remote are not affected.
Still stuck?
- File a bug on GitHub with
shep version,shep status --logs 100and the relevantshep feat logs <id>excerpt. - Ask in Discord .
What’s next
- Getting Started — back to basics if setup is failing.
- Fleet management — the queue, limits and the circuit breaker.
- CLI Reference — every command and flag.