Troubleshooting

Each entry lists symptoms, likely cause, fix, and how to verify.

---

Install failed: vibe: command not found

Symptoms: npm install -g vibestrate succeeded, but vibe --version returns “command not found.”

Likely cause: Your shell’s PATH doesn’t include npm’s global bin directory.

Fix:

npm config get prefix
# Add <prefix>/bin to your PATH in ~/.zshrc or ~/.bashrc

Verify: which vibe returns a real path.

---

vibe init fails: not a git repository

Symptoms: Init refuses to run with a “not a git repository” error.

Likely cause: Vibestrate needs git for worktree isolation. The current directory isn’t initialized.

Fix:

git init
git add -A && git commit -m "Initial commit"
vibe init

Verify: git rev-parse --is-inside-work-tree returns true.

---

vibe doctor reports “no providers ready”

Symptoms: Doctor lists all providers as missing or detected-needs-setup.

Likely cause: No coding-agent CLI is installed on PATH, or none has a verified preset.

Fix: Install at least one:

# Claude Code: see https://docs.anthropic.com/claude/docs/claude-code
# Codex:       npm install -g @openai/codex
# Aider:       pipx install aider-chat
# Ollama:      curl -fsSL https://ollama.com/install.sh | sh

Then:

vibe provider detect
vibe provider setup
vibe provider test <id>

Verify: vibe provider detect shows at least one provider with confidence ready or a working detected-needs-setup after provider setup.

---

Run starts then immediately fails: “validation command not configured”

Symptoms: The run reaches validating, raises “no validation commands configured”, and ends in failed.

Likely cause: commands.validate in project.yml is empty.

Fix:

vibe config set commands.validate '["pnpm typecheck"]'
# or
vibe config set commands.validate '["pnpm typecheck", "pnpm test"]'

Verify: vibe config get commands.validate shows your array.

---

Run stuck in waiting_for_approval

Symptoms: Status is waiting_for_approval and nothing’s happening.

Likely cause: A policy gate at this stage requires explicit human approval (per policies.requireApprovalAtStages).

Fix:

vibe approvals list <runId>
vibe approvals decide <runId> <approvalId> --approve   # or --reject

Verify: Status transitions back to the stage it was about to enter.

---

Run stuck in paused

Symptoms: Status is paused and vibe resume doesn’t seem to do anything.

Likely cause: Either the orchestrator isn’t running (the process that owns the run ended), or the resume hasn’t reached the next polling tick yet.

Fix:

If Vibestrate’s process is alive: vibe resume <runId> and wait a few seconds for the next stage-boundary check.

If the process ended: start it again (vibe run or vibe ui) and the durable state will be picked up automatically.

Verify: vibe status shows the run transitioning out of paused.

---

Provider test fails: “command not found”

Symptoms: vibe provider test claude returns “claude: command not found.”

Likely cause: The provider’s CLI isn’t on the PATH of the shell Vibestrate was started from.

Fix: Add the CLI to your PATH. For shell-installed binaries, restart your terminal so the new PATH is loaded.

Verify: which claude (or whichever CLI) returns a real path.

---

Provider test passes but runs fail with “unexpected output”

Symptoms: vibe provider test returns success, but real runs end with “could not parse provider output.”

Likely cause: The provider’s prompt-flag preset is producing output Vibestrate can’t parse - usually because the provider changed its output format between releases.

Fix:

vibe provider setup    # walk the wizard again to confirm flags

If the flags are right but the output format changed, file an issue with the provider’s version (<cli> --version) and a sample of the captured output (under .vibestrate/runs/<runId>/outputs/).

---

Worktree creation failed: “main branch has uncommitted changes”

Symptoms: Run aborts at start with a requireCleanMain violation.

Likely cause: Your project.yml has git.requireCleanMain: true and main has uncommitted edits.

Fix: Commit or stash, then re-run:

git stash push -m "before vibe run"
vibe run "..."

Or flip the policy if you don’t want it:

vibe config set git.requireCleanMain false

Verify: Worktree appears under ../.vibestrate-worktrees/.

---

Notifications never arrive

Symptoms: Configured a Slack/webhook gateway, ran a task, no notification.

Likely cause: The gateway is registered but disabled, the webhook URL is wrong, or the notification severity is below the gateway’s threshold.

Fix:

vibe gateways list
vibe notifications list

Confirm the gateway is enabled and the webhook URL is reachable. Send a test:

vibe notifications test <gatewayId>

---

Dashboard tab is blank

Symptoms: vibe ui opens, but a tab shows no data even though there are runs.

Likely cause: The browser cached an older asset bundle, or the runs are in a different project root than the one vibe ui was started from.

Fix: Hard-reload (Cmd-Shift-R / Ctrl-Shift-R). Confirm vibe ui is running from the project root you expect: the dashboard reads .vibestrate/runs/ from cwd.

---

Worktree didn’t get cleaned up after abort

Symptoms: vibe abort <runId> succeeded, but ../.vibestrate-worktrees/<runId>-<slug> is still on disk.

Likely cause: This is by design. Worktrees are preserved across aborted, blocked, and failed so you can inspect or copy out partial work.

Fix:

cd your-project
git worktree remove ../.vibestrate-worktrees/<runId>-<slug>
git branch -D vibestrate/<runId>-<slug>

Verify: The directory is gone.