Handbook
Troubleshooting
Common fixes for Lenses, Forge Studio, and the Blueprints Wizard — user-facing symptoms first; build and server tuning for operators stay in the forge-lenses repository.
What it is
Common fixes for Lenses, Forge Studio, and the Blueprints Wizard — user-facing symptoms first; build and server tuning for operators stay in the forge-lenses repository.
When to use it
Something failed during Install and run, Workspace setup, Studio 101, or Wizard 101.
Prerequisites
- Note the symptom (blank page, missing wizard, save errors, etc.).
Fast triage
| Order | Check |
|---|---|
| 1 | Server process running; terminal shows the listen port |
| 2 | URL matches host/port; no stale bookmark |
| 3 | LENSES_WORKSPACE_ROOT points at the parent of your clones (Workspace setup) |
Evidence to gather (for yourself or your operator)
| Item | Why it helps |
|---|---|
| Last 20 lines of server stderr | Shows import, port, or scan errors |
GET /api/workspace-state result |
Separates “UI only” from “server unhealthy” |
Whether Classic / works but /studio/ does not |
Narrows to Studio asset or routing issues |
Steps
| Symptom | Area | What to try |
|---|---|---|
/studio/ blank |
Studio | Confirm the Python server is running and the URL/port match Install and run. If the dashboard works but Studio does not, reinstall or update from a fresh clone and repeat Install and run. If it still fails, ask whoever runs or maintains your Lenses server. |
| Wizard missing | Wizard | Confirm you are in Forge Studio under the Wizard entry points described in Wizard overview. If the feature is disabled in your deployment, ask whoever runs the server to enable it or use a build where it is available. |
| “Local draft only” | Wizard | Ensure Lenses is running; click Retry; check server logs for errors. |
| Wrong repos scanned | Workspace | Set LENSES_WORKSPACE_ROOT to the parent of your clones; restart the server. |
| LLM / Refine errors | Wizard | Confirm loopback policy for local APIs; check server stderr. |
| Save / PUT errors | General | Disk space; permissions on .lenses-local/; avoid multiple tabs on one session for critical saves. |
| Architecture or HTTP details | Maintainer | Use the forge-lenses repository on GitHub — not this public handbook. |
How to verify success
- The blocking issue is gone or you have a clear next step (restart, workspace path, or follow-up with your server operator).