# 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