Skip to content
git-watchtower

Troubleshooting

Git Issues

Section titled “Git Issues”

”Git is not installed or not in PATH”

Section titled “”Git is not installed or not in PATH””

Git Watchtower requires Git. Install it from: https://git-scm.com/downloads

”No Git remote configured”

Section titled “”No Git remote configured””

Git Watchtower requires a remote to watch. Add one with:

Terminal window
git remote add origin <repository-url>

Using a different remote name

Section titled “Using a different remote name”

If your remote isn’t called origin, update your config:

{
  "remoteName": "upstream"
}

Or use the CLI flag:

Terminal window
git-watchtower --remote upstream

Slow fetches / High latency

Section titled “Slow fetches / High latency”

Git Watchtower automatically reduces polling frequency on slow networks. You can also increase the interval:

Terminal window
git-watchtower --poll-interval 10000

Dirty working directory errors

Section titled “Dirty working directory errors”

If branch switching fails because of uncommitted changes, press S to stash your changes. Git Watchtower will prompt for confirmation before stashing.

Server Issues

Section titled “Server Issues”

Port already in use

Section titled “Port already in use”

Try a different port:

Terminal window
git-watchtower -p 3001

Server crashes immediately (custom server command mode)

Section titled “Server crashes immediately (custom server command mode)”
  • Check that your command works when run directly
  • View logs with l to see error messages
  • Try restarting with R

Sound not working

Section titled “Sound not working”
  • macOS: Uses system sounds via afplay
  • Linux: Requires PulseAudio (paplay) or ALSA (aplay)
  • Windows: Uses terminal bell

Toggle sound with s or set "soundEnabled": false in config.

Web Dashboard Issues

Section titled “Web Dashboard Issues”

Web dashboard port conflict

Section titled “Web dashboard port conflict”

If port 4000 is in use, the dashboard automatically tries the next port (up to 20 retries). Check the TUI status bar for the actual port.

You can also specify a custom port:

Terminal window
git-watchtower --web --web-port 8080

Multiple instances not showing in dashboard

Section titled “Multiple instances not showing in dashboard”

Multi-instance coordination uses Unix domain sockets at ~/.watchtower/web.sock. If instances aren’t appearing:

  1. Check that ~/.watchtower/web.lock exists and its PID is alive
  2. If the lock file references a dead process, delete it and restart:
    Terminal window
    rm ~/.watchtower/web.lock ~/.watchtower/web.sock
  3. Restart your git-watchtower instances

Browser not opening automatically

Section titled “Browser not opening automatically”

The web dashboard auto-opens a browser tab on first launch. If this doesn’t work:

  • Open http://localhost:4000 manually (or the port shown in the TUI)
  • On headless systems, the browser open is skipped automatically

Live reload not working on Windows

Section titled “Live reload not working on Windows”

Static-mode live reload uses Node.js fs.watch() with recursive watching. Recursive fs.watch is unreliable on some filesystems on Windows (notably non-NTFS volumes and network drives). If you see a warning at startup or live reload doesn’t fire, try one of:

  • Move the project to a local NTFS volume
  • Switch to custom server command mode and rely on your dev server’s own file watcher (git-watchtower --mode command -c "npm run dev")
  • Press r in the TUI to manually trigger a browser reload

Version Updates

Section titled “Version Updates”

Git Watchtower checks for new versions via the npm registry and shows a notification in the TUI when an update is available. Update with:

Terminal window
npm install -g git-watchtower@latest