b29c12d5e5
Final rebrand: rename remaining Rust source file to complete the gsd → forge transition. All parser references already use forge_parser after earlier commits. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
151 lines
3.8 KiB
Markdown
151 lines
3.8 KiB
Markdown
# Troubleshooting
|
|
|
|
## `/sf doctor`
|
|
|
|
The built-in diagnostic tool validates `.sf/` integrity:
|
|
|
|
```
|
|
/sf doctor
|
|
```
|
|
|
|
It checks file structure, roadmap ↔ slice ↔ task consistency, completion state, git health, stale locks, and orphaned records.
|
|
|
|
## Common Issues
|
|
|
|
### Auto mode loops on the same unit
|
|
|
|
The same unit dispatches repeatedly.
|
|
|
|
**Fix:** Run `/sf doctor` to repair state, then `/sf auto`. If it persists, check that the expected artifact file exists on disk.
|
|
|
|
### Auto mode stops with "Loop detected"
|
|
|
|
A unit failed to produce its expected artifact twice.
|
|
|
|
**Fix:** Check the task plan for clarity. Refine it manually, then `/sf auto`.
|
|
|
|
### `command not found: sf` after install
|
|
|
|
npm's global bin directory isn't in `$PATH`.
|
|
|
|
**Fix:**
|
|
```bash
|
|
npm prefix -g
|
|
# Add the bin dir to PATH:
|
|
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
|
|
source ~/.zshrc
|
|
```
|
|
|
|
**Common causes:**
|
|
- **Homebrew Node** — `/opt/homebrew/bin` missing from PATH
|
|
- **Version manager (nvm, fnm, mise)** — global bin is version-specific
|
|
- **oh-my-zsh** — `gitfast` plugin aliases `sf` to `git svn dcommit`; check with `alias sf`
|
|
|
|
### Provider errors during auto mode
|
|
|
|
| Error Type | Auto-Resume? | Delay |
|
|
|-----------|-------------|-------|
|
|
| Rate limit (429) | Yes | 60s or retry-after header |
|
|
| Server error (500, 502, 503) | Yes | 30s |
|
|
| Auth/billing ("unauthorized") | No | Manual resume required |
|
|
|
|
For permanent errors, configure fallback models:
|
|
|
|
```yaml
|
|
models:
|
|
execution:
|
|
model: claude-sonnet-4-6
|
|
fallbacks:
|
|
- openrouter/minimax/minimax-m2.5
|
|
```
|
|
|
|
### Budget ceiling reached
|
|
|
|
Auto mode pauses with "Budget ceiling reached."
|
|
|
|
**Fix:** Increase `budget_ceiling` in preferences, or switch to `budget` token profile, then `/sf auto`.
|
|
|
|
### Stale lock file
|
|
|
|
Auto mode won't start, says another session is running.
|
|
|
|
**Fix:** SF auto-detects stale locks (dead PID = auto cleanup). If automatic recovery fails:
|
|
|
|
```bash
|
|
rm -f .sf/auto.lock
|
|
rm -rf "$(dirname .sf)/.sf.lock"
|
|
```
|
|
|
|
### Git merge conflicts
|
|
|
|
Worktree merge fails on `.sf/` files.
|
|
|
|
**Fix:** `.sf/` conflicts are auto-resolved. Code conflicts get an AI fix attempt; if that fails, resolve manually.
|
|
|
|
### Notifications not appearing on macOS
|
|
|
|
**Fix:** Install `terminal-notifier`:
|
|
|
|
```bash
|
|
brew install terminal-notifier
|
|
```
|
|
|
|
See [Notifications](../configuration/notifications.md) for details.
|
|
|
|
## MCP Issues
|
|
|
|
### No servers configured
|
|
|
|
**Fix:** Add server to `.mcp.json` or `.sf/mcp.json`, verify JSON is valid, run `mcp_servers(refresh=true)`.
|
|
|
|
### Server discovery times out
|
|
|
|
**Fix:** Run the configured command outside SF to confirm it starts. Check that backend services are reachable.
|
|
|
|
### Server connection closed immediately
|
|
|
|
**Fix:** Verify `command` and `args` paths are correct and absolute. Run the command manually to catch errors.
|
|
|
|
## Recovery Procedures
|
|
|
|
### Reset auto mode state
|
|
|
|
```bash
|
|
rm .sf/auto.lock
|
|
rm .sf/completed-units.json
|
|
```
|
|
|
|
Then `/sf auto` to restart from current state.
|
|
|
|
### Reset routing history
|
|
|
|
```bash
|
|
rm .sf/routing-history.json
|
|
```
|
|
|
|
### Full state rebuild
|
|
|
|
```
|
|
/sf doctor
|
|
```
|
|
|
|
Rebuilds `STATE.md` from plan and roadmap files and fixes inconsistencies.
|
|
|
|
## Getting Help
|
|
|
|
- **GitHub Issues:** [github.com/sf-build/SF/issues](https://github.com/sf-build/SF/issues)
|
|
- **Dashboard:** `Ctrl+Alt+G` or `/sf status`
|
|
- **Forensics:** `/sf forensics` for post-mortem analysis
|
|
- **Session logs:** `.sf/activity/` contains JSONL session dumps
|
|
|
|
## Platform-Specific Issues
|
|
|
|
### iTerm2
|
|
|
|
`Ctrl+Alt` shortcuts trigger wrong actions → Set **Profiles → Keys → General → Left Option Key** to **Esc+**.
|
|
|
|
### Windows
|
|
|
|
- LSP ENOENT on MSYS2/Git Bash → Fixed in v2.29+, upgrade
|
|
- EBUSY errors during builds → Close browser extension, or change output directory
|
|
- Transient EBUSY/EPERM on `.sf/` files → Retry; close file-locking tools if persistent
|