gsd-pi

Troubleshooting

Start here when GSD is stuck, noisy, or behaving differently than expected.

Quick checks

Run the built-in doctor first:

/gsd doctor

If it reports fixable issues, run:

/gsd doctor fix

Doctor checks the .gsd/ directory, roadmap/slice/task references, runtime state, and Git worktree health.

After fixing the issue, resume with:

/gsd auto

Common issues

Upgrade from older gsd-pi installs

Symptoms: gsd reports a version mismatch, a managed-resource mismatch, or the old unscoped gsd-pi package is still being used.

Fix: Remove the old global package and install the scoped package.

macOS / Linux:

sudo npm uninstall -g gsd-pi
rm -f ~/.gsd/.update-check ~/.gsd/agent/managed-resources.json
sudo npm install -g @opengsd/gsd-pi@latest

Windows PowerShell:

Remove-Item "$env:USERPROFILE\.gsd\.update-check" -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\.gsd\agent\managed-resources.json" -Force -ErrorAction SilentlyContinue
npm install -g @opengsd/gsd-pi@latest

You can also run the installer:

npx @opengsd/gsd-pi@latest

After setup, routine upgrades use gsd upgrade, gsd update, or /gsd update.

command not found: gsd after install

Symptoms: Install succeeds, but your shell cannot find gsd.

Fix: Add npm's global bin directory to your PATH.

npm prefix -g
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

If you use nvm, fnm, mise, or another version manager, make sure it initializes in your shell profile.

pnpm says the global bin directory is not in PATH

Symptoms: pnpm add -g or pnpm remove -g fails because the global bin directory is not in PATH.

Fix:

pnpm setup
exec $SHELL -l
pnpm add -g @opengsd/gsd-pi@latest

Install fails

Common checks:

  • Use Node.js 22 or newer.
  • Upgrade to the latest @opengsd/gsd-pi.
  • If an old global install used sudo, remove it with sudo npm uninstall -g gsd-pi.

Auto mode loops, pauses, or will not continue

Fix:

  1. Run /gsd doctor.
  2. If doctor offers fixes, run /gsd doctor fix.
  3. Check the latest milestone, slice, or task file for missing artifacts or unclear instructions.
  4. Resume with /gsd auto.

If the same unit keeps repeating, clarify the task plan or split the work into smaller tasks.

Provider errors during auto mode

Symptoms: Auto mode pauses because of rate limits, server errors, authentication errors, or billing errors.

Fix:

  • Wait and retry for rate limits or temporary provider outages.
  • Recheck provider credentials for auth or billing errors.
  • Configure fallback models if one provider is unreliable.
models:
  execution:
    model: claude-sonnet-4-6
    fallbacks:
      - openrouter/minimax/minimax-m2.5

For provider setup details, see Providers.

Budget ceiling reached

Symptoms: Auto mode pauses with "Budget ceiling reached."

Fix: Increase budget_ceiling in preferences, switch to a lower-cost token profile, then resume with /gsd auto.

Auto mode says another session is running

Fix: Run /gsd doctor fix, then retry /gsd auto. Doctor clears stale runtime ownership in most cases.

Git merge conflicts

Symptoms: /gsd commands are blocked, or auto mode pauses with unresolved Git conflicts.

Fix:

  1. Resolve the conflicts in your source files.
  2. Run git status and confirm the conflicting paths are clean.
  3. Run /gsd doctor.
  4. Retry the original command.

Wrong files in worktree

Symptoms: Planning artifacts or code appear in the wrong directory.

Fix: Upgrade to the latest GSD version, then run /gsd doctor. Newer dispatch prompts include explicit working-directory instructions.

MCP tools are missing or failing

Basic checks:

  • Confirm .mcp.json or .gsd/mcp.json exists in the project you launched GSD from.
  • Verify the JSON is valid.
  • Use absolute paths for local server commands and scripts.
  • Run the configured command manually to catch startup errors.
  • Re-run MCP discovery after changing config.

Web mode cannot start

Symptoms: gsd --web fails, often because port 3000 is already in use.

Fix: Upgrade to the latest version. If an older orphan server is still running, stop it manually:

lsof -ti:3000 | xargs kill

LSP is not available

Symptoms: GSD reports that language-server features are unavailable.

Fix: Run:

lsp status

Install the language server for your project type, then run:

lsp reload

Windows file lock errors

Symptoms: Windows reports EPERM, EBUSY, or EACCES while GSD is updating .gsd/ files or worktrees.

Fix: Close editors, terminals, antivirus tools, or watchers that may be holding files open, then retry the command.

Notifications not appearing on macOS

Symptoms: notifications.enabled: true is set, but no desktop notifications appear.

Fix: Install terminal-notifier:

brew install terminal-notifier

GSD prefers terminal-notifier when available. macOS should prompt for notification permission on first use.

To test notifications:

terminal-notifier -title "GSD" -message "working!" -sound Glass

Telegram notifications not arriving

Basic checks:

  • Set notifications.enabled: true.
  • Run /gsd remote status.
  • Re-run setup with /gsd remote telegram.
  • Confirm the bot is in the target chat.
  • Confirm the configured channel_id matches the chat.
  • Test network access to https://api.telegram.org.

Recovery

Use recovery commands only after the basic checks above.

Refresh derived state:

/gsd doctor fix

Recover the database from markdown artifacts:

/gsd recover

For scripts or CI:

gsd headless recover

Getting help

  • GitHub Issues
  • /gsd status for current session status
  • /gsd forensics for auto-mode failure details
  • .gsd/activity/ for session logs

source: gsd-pi/docs/user-docs/troubleshooting.md