Start With the Symptom
- Workflow state, stuck runs, and SQLite inspection: Debugging
- Retries, timeouts, skips, and graceful degradation: Error Handling
- File-watcher and prompt reload behavior: Hot Reload
- Event streaming, approvals, and server APIs: Server Integration
- Workspace snapshots and revert behavior: VCS Integration
Common Failure Modes
A task did not rerun
Smithers resumes byrunId. If a node already completed for the current runId, it will be skipped on resume. Use a new runId for a fresh run, or inspect the persisted attempts with the CLI before assuming the scheduler is stuck.
An MDX prompt rendered as [object Object]
That usually means the MDX preload was not registered. Confirm that your preload script calls mdxPlugin() and that bunfig.toml points at the preload file.
The workflow code changed but the running task did not
Hot reload only affects work that has not been scheduled yet. In-flight tasks continue with the code and prompt they started with.When in Doubt
- Check
smithers statusfor the current run. - Inspect recent frames with
smithers frames. - Query the SQLite database if the CLI summary is not enough.