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 .

Setup

command not found: shep

Either Shep isn’t installed, or your global npm bin isn’t on PATH.

npm i -g @shepai/cli
which shep
npm bin -g     # path that should be in your PATH

If you used npx (npx @shepai/cli), there’s no globally installed binary — you have to keep using npx.

Node.js 22+ required

Update Node.js. The easiest way is nvm:

nvm install 22
nvm use 22

Verify with node --version.

gh: command not found

Install GitHub CLI. See cli.github.com .

gh auth login           # follow prompts
gh auth status          # confirm

Agent not detected (claude / cursor / gemini)

Make sure the binary is on your PATH:

which claude
which cursor
which gemini

If one of those returns “not found,” install the agent. Then re-run shep settings agent to make Shep pick it up.

Daemon

Port 4050 already in use

Another process is using the port. Either stop it or run Shep on a different port:

SHEP_PORT=4051 shep
shep ui --port 4051

shep status says “not running”

Start the daemon:

shep start

If shep start errors, check the logs:

ls ~/.shep/logs
tail -n 100 ~/.shep/logs/daemon.log

shep stop doesn’t actually stop it

Sometimes the process gets stuck. Force kill:

ps aux | grep shep
kill -9 <pid>

Then shep start again.

Authentication

Agent says “not authenticated”

Shep doesn’t store agent credentials. The agent must work standalone first:

claude --version          # or cursor / gemini

If that fails, re-authenticate the agent itself, then re-try Shep.

gh says you’re authenticated but pushes fail

Check that you’re authenticated for the right account and have push access to the repo:

gh auth status
gh repo view --json viewerPermission

If permission is READ you can’t push. Either fork the repo or get push access.

Features

Feature stuck in “Started” phase

Usually the daemon couldn’t launch the agent. Check the feature logs:

shep feat logs <id>

Look for errors like “agent not found,” “permission denied,” or “out of context.”

Agent gets stuck in a loop

Stop it and provide feedback:

shep agent stop <id>
shep feat reject <id> --feedback "the agent kept reformatting the same file — can you focus only on the controller?"
shep feat resume <id>

Worktree directory missing

If you rm -rf a worktree by accident, Shep can’t recreate it. Delete the feature and start over:

shep feat del <id>

The branch on the remote (if you pushed) is preserved.

”Branch already exists”

You probably already have a branch with the same name. Either delete it or use a different feature description (which generates a different slug).

git branch -D feat/your-feature-slug      # locally
git push origin --delete feat/your-feature-slug   # remotely if needed

CI

CI never starts

Make sure your repo has GitHub Actions configured and that gh has the right permissions. Manually trigger a run from the PR to confirm.

Auto-fix loops without converging

After 3 retries (configurable), Shep pauses the feature. Read the agent’s last commit and the failing CI logs together — usually the agent is misunderstanding the error. Provide a more specific prompt:

shep feat reject <id> --feedback "the failing test is testing X — the issue is likely Y, please look at file Z"
shep feat resume <id>

Analysis

Repo analysis is slow

Large repos take longer on first run. Limit scope in .shep/config.json:

{
  "analysis": {
    "additionalExcludes": ["**/large-folder/**", "**/generated/**"],
    "maxFileSize": 524288,
    "maxFiles": 5000
  }
}

Re-run analysis manually

Delete the cached analysis and re-run:

rm -rf .shep/analysis
shep    # re-runs analysis on next start

Dashboard

Dashboard won’t open

shep status

If the daemon is running, open localhost:4050  directly in your browser.

If the daemon isn’t running:

shep start

Dashboard loads but is blank

Hard-refresh (Cmd/Ctrl + Shift + R) to bypass cached assets. If still blank:

shep stop
shep start

Resetting everything

If Shep is in a state you can’t fix, nuke it:

shep stop
rm -rf ~/.shep
npm uninstall -g @shepai/cli
npm i -g @shepai/cli
shep                 # re-runs first-time setup

Worktrees and branches not under ~/.shep/ (i.e., real branches on remote) are preserved.

Still stuck?

  • File a bug on GitHub  with shep status output and the relevant shep feat logs <id> excerpt.
  • Ask in Discord  — usually answered within an hour during US/EU business hours.
FAQ