---
title: "Troubleshooting"
description: "Common issues, /sf doctor, /sf forensics, and recovery procedures."
---

## `/sf doctor`

The built-in diagnostic tool validates `.sf/` integrity:

```
/sf doctor
```

It checks file structure, referential integrity, completion state consistency, git worktree health, and stale lock files.

## Common issues

<AccordionGroup>
  <Accordion title="Auto mode loops on the same unit">
    **Cause:** Stale cache after a crash, or the LLM didn't produce the expected artifact.

    **Fix:** Run `/sf doctor` to repair state, then `/sf auto`.
  </Accordion>

  <Accordion title="Auto mode stops with 'Loop detected'">
    **Cause:** A unit failed to produce its expected artifact twice in a row.

    **Fix:** Check the task plan for clarity. Refine it manually, then `/sf auto`.
  </Accordion>

  <Accordion title="command not found: sf">
    **Cause:** npm's global bin directory isn't in `$PATH`.

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

    **Workaround:** `npx sf-run` or `$(npm prefix -g)/bin/sf`
  </Accordion>

  <Accordion title="Provider errors during auto mode">
    | Error type | Auto-resume? | Delay |
    |-----------|-------------|-------|
    | Rate limit (429) | Yes | retry-after or 60s |
    | Server error (500, 502, 503) | Yes | 30s |
    | Auth/billing | No | Manual resume |

    For transient errors, configure fallback models:
    ```yaml
    models:
      execution:
        model: claude-sonnet-4-6
        fallbacks:
          - openrouter/minimax/minimax-m2.5
    ```
  </Accordion>

  <Accordion title="Budget ceiling reached">
    Increase `budget_ceiling` in preferences, or switch to `budget` token profile. Resume with `/sf auto`.
  </Accordion>

  <Accordion title="Stale lock file">
    SF auto-detects stale locks. If automatic recovery fails:
    ```bash
    rm -f .sf/auto.lock
    rm -rf "$(dirname .sf)/.sf.lock"
    ```
  </Accordion>

  <Accordion title="Git merge conflicts on .sf/ files">
    SF auto-resolves conflicts on `.sf/` runtime files. For code conflicts, the LLM attempts resolution. If that fails, resolve manually.
  </Accordion>

  <Accordion title="EBUSY / EPERM / EACCES on Windows">
    **Cause:** Antivirus, indexers, or editors briefly locking files during atomic rename.

    **Fix:** Re-run the operation. Close tools holding files open if the error persists. Run `/sf doctor` to verify repo health.
  </Accordion>

  <Accordion title="Worktree isolation stopped working after upgrade to v2.45+">
    **Cause:** The default `git.isolation` mode changed from `worktree` to `none` in v2.45.0.

    **Fix:** Set `git.isolation: worktree` explicitly in your preferences:
    ```yaml
    git:
      isolation: worktree
    ```
  </Accordion>

  <Accordion title="Node.js version or git not found at startup">
    **Cause:** SF v2.45+ checks for Node.js >= 22 and git availability at startup.

    **Fix:** Install Node.js 22+ (24 LTS recommended) and ensure `git` is in your PATH.
  </Accordion>
</AccordionGroup>

## `/sf forensics`

Full-access debugger for post-mortem analysis:

```
/sf forensics [optional problem description]
```

Provides anomaly detection, unit traces, metrics analysis, doctor integration, and LLM-guided investigation.

## MCP client issues

Use `/sf mcp` to check MCP server status and connectivity at a glance.

<AccordionGroup>
  <Accordion title="No configured servers">
    Verify `.mcp.json` or `.sf/mcp.json` exists and parses as valid JSON.
  </Accordion>

  <Accordion title="mcp_discover times out">
    Run the configured command outside SF to confirm the server starts. Check backend URLs and dependencies.
  </Accordion>

  <Accordion title="Local server works manually but not in SF">
    Use absolute paths. Set required environment variables in the MCP config's `env` block.
  </Accordion>
</AccordionGroup>

## Recovery procedures

### Reset auto mode state

```bash
rm .sf/auto.lock
rm .sf/completed-units.json
```

Then `/sf auto` to restart from current disk state.

### Reset routing history

```bash
rm .sf/routing-history.json
```

### Full state rebuild

```
/sf doctor
```

Rebuilds `STATE.md` from plan and roadmap files on disk.

## Getting help

- **GitHub Issues:** [github.com/sf-build/SF/issues](https://github.com/sf-build/sf-2/issues)
- **Dashboard:** `Ctrl+Alt+G` or `/sf status`
- **Forensics:** `/sf forensics`
- **Session logs:** `.sf/activity/`
