Harmony ChatGuides
Troubleshooting
Where to look when a piece is not answering.
Start at the edge and move in.
curl -sf http://127.0.0.1:8080/health
bun run harmony -- health| Symptom | Check first |
|---|---|
| Web page loads, nothing saves | /health on :8080 — the page and the API are separate origins |
| Server starts, then requests stall | PGlite is embedded; a long first boot is normal on cold caches |
| Login screen appeared unexpectedly | You moved off loopback; local_trusted only applies to :8080 on 127.0.0.1 |
| Worker missing from Capacity | Token mismatch — HARMONY_WORKER_TOKEN must match the main |
| Worker visible, agent still offline | The session's pin is on that worker; pins do not fail over |
| Agent DM shows no harness output | The harness process is on the worker, not on the main host |
| Second server refuses to start | $HARMONY_HOME has a run-state lock; one main per home |
Two servers at once
One $HARMONY_HOME runs one main server. For a second instance, give it its own home:
HARMONY_HOME=/tmp/harmony-two harmony server start --port 8090Before reporting
Capture the three things that make a report actionable: the listener flag, the output of
harmony health, and whether the failing piece is main or a worker. Redact tokens and hostnames.