Skip to Content
Troubleshooting

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 state

Add --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 PATH

If 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 22

better-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-scripts

If 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 status

Agent 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 # Cline

shep 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 running

shep status says “not running”

Start the daemon:

shep start

If that fails, read the daemon log:

shep status --logs 100 # last 100 lines shep status -f # follow it

The 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 left

Then 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, cline

If 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 viewerPermission

If 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 limit

Nothing 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 failed

Pause 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 or shep 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 needed

npm 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 hand

Commands 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 events

DO_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 status

If 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 restart

Resetting 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 again

rm -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 100 and the relevant shep feat logs <id> excerpt.
  • Ask in Discord .

What’s next