When it breaks
Start from the symptom, not the topic. Nine things you might be looking at, each with one cause and one command.
Find what you are seeing
Nothing moves at all no events
On the board this reads as
no events Cause The gateway is not running, so no dispatcher is sweeping the board.
hermes gateway start What to do about it Check the gateway before anything else. No gateway means no ticks, and the board looks identical to a board with no work.
One card sits in Todo forever no runs
On the board this reads as
no runs Cause It is waiting on a parent, or its assignee is not a profile that exists.
hermes profile list What to do about it Compare the assignee on the card with that list. A typo here is silent by design.
Two failed attempts, then it stopped gave_up
On the board this reads as
gave_up Cause The circuit breaker tripped after failure_limit attempts, which is 2 by default.
hermes kanban runs t_abcd What to do about it Read the error on the attempts. Identical messages mean the environment is wrong, not the work.
The worker vanished mid-job crashed
On the board this reads as
crashed Cause The process died: out of memory, killed, or the machine slept.
hermes kanban runs t_abcd What to do about it The dispatcher reclaims the card and a fresh worker gets it, which can read why the last one died.
A card came back after hours of silence stale
On the board this reads as
stale Cause It missed its heartbeat, so the dispatcher stopped believing the worker was alive.
hermes kanban show t_abcd What to do about it Long jobs must heartbeat at least hourly. The stale timeout is 4 hours.
It stopped and asked me something blocked
On the board this reads as
blocked Cause A worker called kanban_block on purpose rather than guessing.
hermes kanban unblock t_abcd What to do about it Answer or fix the thing it names, then unblock. It returns to Ready and a fresh worker picks it up.
It keeps blocking on the same thing block_loop_detected
On the board this reads as
block_loop_detected Cause The same card blocked for the same reason twice, so the board stopped the loop.
hermes kanban show t_abcd What to do about it Two identical blocks mean the card is unanswerable as written. Rewrite the card, do not unblock it again.
The worker did something malformed protocol_violation
On the board this reads as
protocol_violation Cause The agent produced output the board could not accept, three times.
hermes kanban runs t_abcd What to do about it Usually a profile without the kanban tools, or a model too small to follow the contract. Change the profile, not the card.
It ran out of time timed_out
On the board this reads as
timed_out Cause The card exceeded its allowed run time and was cut off.
hermes kanban runs t_abcd What to do about it Either the card is too big for one worker, or it needed to be several cards with parents.
Nothing is happening at all
- 1
· The gateway is not running.
hermes gateway start - 2
· The assignee does not exist.
hermes profile list - 3 · The card sits in Todo waiting on another card to finish first.
- 4
· You are looking at a different board.
hermes kanban boards show - 5 · Another gateway owns the dispatcher. Exactly one keeps kanban.dispatch_in_gateway true; every other gateway must set it to false, or two dispatchers fight over the same claims.
Screen 6 of 7.