Troubleshooting

Common setup, runtime, and workflow issues with diagnosis paths.

By Subsystem

Symptom	Guide
Workflow state, stuck runs, SQLite inspection	Debugging
Retries, timeouts, skips, graceful degradation	Error Handling
File-watcher and prompt reload behavior	Hot Reload
Event streaming, approvals, server APIs	Server Integration
Workspace snapshots and revert behavior	VCS Integration

Common Failures

A task did not rerun — Smithers resumes by runId. If a node already completed for the current runId, it is skipped. Use a new runId for a fresh run, or inspect persisted attempts first.

MDX prompt rendered as [object Object] — The MDX preload was not registered. Confirm preload.ts calls mdxPlugin() and bunfig.toml points at the preload file.

Workflow code changed but running task did not — Hot reload only affects unscheduled work. In-flight tasks continue with the code they started with.

General Diagnosis

smithers inspect <runId>
smithers logs <runId> --tail 20 --follow false

If the CLI summary is insufficient, query SQLite directly. See Debugging.

Agent Diagnostics

When a CLI agent fails, Smithers automatically runs diagnostics to check for common issues (binary not installed, API key invalid, rate limit hit). The diagnostic summary is printed to stderr:

[diagnostics] claude: api_key_valid=fail: Rate limit detected in error (142ms)

The full diagnostic report is also attached to the error’s details.diagnostics field for programmatic inspection.