Troubleshooting

gwt doctor

The quickest way to diagnose problems:

gwt doctor

This checks all prerequisites and shows what’s working and what’s not.

Common issues

gwt command not found

If you use oh-my-zsh, its git plugin aliases gwt to git worktree. Add to your .zshrc:

unalias gwt 2>/dev/null

Zellij not found

Install Zellij: zellij.dev/documentation/installation

gwt requires Zellij for session management. Without it, gwt attach will fail.

Gateway port already in use

If gwt gateway start fails because the port is taken:

gwt gateway status   # Check if a gateway is already running
gwt gateway stop     # Stop the existing one

Or use a different port:

gwt gateway start --port 9000

Stale PID file

If gwt gateway status shows “running” but the process is dead:

gwt gateway stop   # Cleans up the stale PID file

The gateway also cleans up stale PID files automatically on post-switch hooks.

Diffity not available

✗ diffity (npx not found — install Node.js for code review features)

Install Node.js to enable Diffity. gwt detects it at runtime — no reconfiguration needed. After installing, verify with gwt doctor.

Cannot remove current worktree

Cannot remove the current worktree. Switch to a different worktree first.

Switch to another branch before removing:

gwt switch main
gwt remove feat/old-branch

Worktree does not exist (auto-create disabled)

Worktree for 'feat/x' does not exist. Use 'gwt create feat/x' first.

Either create the worktree explicitly or enable auto-creation:

[worktree]
auto-create = true

Branch not fully merged

When gwt remove or gwt merge warns about an unmerged branch, it keeps the branch to prevent data loss. If you’re sure the branch is safe to delete:

git branch -D feat/old-branch