9d739dfa5d
- All gsdDir/gsdRoot/gsdHome → sfDir/sfRootDir/sfHome - GSDWorkspace* → SFWorkspace* interfaces - bootstrapGsdProject → bootstrapProject - runGSDDoctor → runSFDoctor - GsdClient → SfClient, gsd-client.ts → sf-client.ts - .gsd/ → .sf/ in all tests, docs, docker, native, vscode - Auto-migration: headless detects .gsd/ → renames to .sf/ - Deleted gsd-phase-state.ts backward-compat re-export - Renamed bin/gsd-from-source → bin/sf-from-source - Updated mintlify docs, github workflows, docker configs
158 lines
4.4 KiB
Text
158 lines
4.4 KiB
Text
---
|
|
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/`
|