Fabric handbook · Executor + Studio
Troubleshooting and recovery
Find the exact failing boundary before retrying. Preserve the run’s evidence and existing configuration while you investigate.
◇
Reference
Installer or app launch fails
| Symptom | Action |
|---|---|
| Missing QUICK-START.md / package support file | This was a packaging defect fixed in 2026.9.12. Obtain the current installer. Do not create files inside the signed payload. |
| Unexpected .fabric_* state in app / verification failure | Runtime state must live outside the verified package. Use a corrected installer; retain logs and data for migration/repair. |
| Apple cannot verify the app | Check that you extracted the intended notarized release from the approved ZIP. Ask for a verified replacement rather than altering quarantine or signatures. |
| Executor installed but Studio missing | Capture the installer error and its log. Repair with the matched suite; do not assume partial installation succeeded. |
| Studio will not open / wrong old window | Check installed release and launch location. Use the current app; report stale-process/readiness problems to the maintainer. |
| Missing Dock icon | Launch the installed bundle from Finder and re-add that app to the Dock after a successful repair. Do not keep a Dock link to a deleted version. |
The installer’s diagnostic path is shown in its error dialog; commonly ~/Library/Logs/Fabric/Installer/install-error.log. Keep the exact release number and failing verification text.
◇
Reference
Backend unavailable or a run suddenly stops
- Distinguish a disconnected browser from a stopped backend. Check Backend status, worker counts and the retained job stage; avoid starting a second backend manually.
- Wait for an in-progress start/restart to finish. The launch service supervises the process but cannot guarantee recovery from every fault.
- If a job may have written externally, inspect its retained checkpoint and the external system before retrying. Unknown completion requires reconciliation.
- When work is idle, use the Backend panel’s Restart and wait for a fresh Ready state. Hard reset is subject to active-work guards.
- If restarts repeat, capture the backend/service logs, version, time, last stage and model/tool in use. Do not delete configuration/state or continually kill the process.
Closing the browser does not cancel a durable job. Recover queued work may recover queued dispatch; it does not prove that an interrupted operation is safe to replay. Operations guide.
◇
Reference
Repository and Perforce errors
| Message | Fix |
|---|---|
| repository root does not exist | Set General → Paths → Live-data repository to the real gotm_livedata checkout; Save paths and restart when prompted and idle. |
| must be the root of a valid Git checkout | Select the checkout’s root, not client/Assets or an empty folder. Ask your team to clone the repository through its usual Git workflow. |
| Client root MISMATCH | Set the exact root reported by the selected Perforce client in both relevant settings. A parent ~/Perforce folder is often the cause. |
| p4 CLI not found | P4V may be installed without p4. Install the supported CLI, Auto-detect, then Save & test. |
| P4 login/ticket/trust error | Use the same CLI, server and user to complete your team’s login/trust process, then test again. |
| Depot file outside client view | Inspect the exact ticket path and mapping with the maintainer; do not guess another path or submit changes. |
◇
Reference
Agent, safety and publishing failures
| Message / situation | Next step |
|---|---|
| Explicit typed faction and member manifest is required | Select the intended workflow and supply its required authoritative member data. |
| Emergency stop active, stale or unavailable | Inspect General → Emergency-stop safety. Initialize only when offered for a configured new authority; resolve an active stop through the authorized process. |
| Certification or commissioning missing | Request the appropriate verified package/evidence and Executor admission. Do not copy receipt files or inflate scores. |
| All approved assets already match HEAD | Reconcile prior source-control and downstream delivery. This does not establish that Sheets or Jira are complete. |
| Awaiting merge | Review and merge the exact draft PR through the team’s normal process, then verify the checkpoint. Do not rerun preparation to bypass the wait. |
| Unapproved changed files | Preserve unrelated work and resolve the publication scope. A broad git add or direct-main push is not a fix. |
| Unknown completion | Inspect whether the effect happened before deciding to resume. Retrying can duplicate external changes. |
◇
Reference
Knowledge and connector problems
| Symptom | Next step |
|---|---|
| Google Sign in disabled | Import a registered Desktop OAuth client JSON; then complete browser consent. No client means no OAuth sign-in. |
| Google authorized but sheet denied | Verify sharing and read/write scope for the exact sheet and tab; workflow approval is also required for writes. |
| Confluence token saved, page unavailable | Test page access; check URL, page permissions, network and token validity. |
| Photoshop app ready / pair UXP | Open Photoshop, load the supplied provider and complete pairing; inspect the current release’s plugin path. |
| Unity bridge offline | Start the bridge in the correct project and match its loopback port. The dashboard port is not the bridge port. |
| RAG Not built / Blocked / Degraded | Check embedder, source permissions, freshness and source-level errors; rebuild after correcting them. |
| Graphify unavailable / stale | Check installation, provider activation, project binding and indexed SHA; refresh and inspect last error. |
| Setup imported but settings unchanged | Select and Apply the imported draft Environment profile. |
◇
Reference
Send a useful support report
Include Fabric version, macOS/chip, whether this is Executor or Studio, time of failure, workspace/agent version, ticket/run ID, exact failed stage, relevant error text, and what happened immediately before it. For installation errors include the installer log path and excerpt.
Keep passwords, tokens, pairing secrets and private sheet contents out of shared logs/screenshots. Contact Aravindh Subramanian with the smallest useful evidence.