docs / troubleshooting

Troubleshooting

The short list of things that go wrong, and the fix for each.

macOS blocks the app

Builds are not yet notarized with an Apple Developer ID, so Gatekeeper flags the first launch. Either install through Homebrew with --no-quarantine, or launch once and approve the app under System Settings, Privacy and Security, Open Anyway.

Port already in use

The standalone server defaults to port 3002. Pick another with PORT=3010 pnpm start:server. The desktop app's embedded server always uses a free ephemeral port, so it never conflicts.

A session will not go away

Sessions are server-side by design; closing a window does not kill them. Close the terminal from the app (the x button in the terminal header) to terminate the process, or let the idle cleanup reap it after 24 hours.

Dev build fails with spawn npx EACCES

Fixed in 0.2.0. Pull the latest main and run pnpm install once, then pnpm dev:desktop.

The worktree list shows a branch that no longer exists

Press the refresh button in the Worktrees sidebar. If a worktree was deleted outside VibeTree, run git worktree prune in the repository.

Something else

Open an issue on GitHub with what you did, what you expected, and what happened. Logs from the terminal panel help.