A2A troubleshooting
Messages that seem to vanish, agents that look busy and are not, and channels that do not deliver.
Almost every A2A problem is one of three things: the message never started work, the agent is not what you think it is, or the mode forbids it.
Check delivery state before anything else.
nala agent delivery-status <message-id>
Five of the six states mean work has not begun. See delivery lifecycle.
I sent a message and nothing happened
Likely causes, in order of how often they are the answer
needs_enter— the text reached the agent's composer and was never submitted.queued_behind— accepted, waiting behind other work.idle— the agent is at an empty prompt, which usually means your message never arrived at all.- A2A mode is
Off.
Expected evidence: the delivery state names which of these it is.
Repair: depends entirely on the state, which is the point of checking first.
IMPORTANT
needs_enter is the one that fools people. The agent is alive, the text is
visible, and nothing will ever run. From the outside it looks identical to an
agent working.
When not to retry: do not re-send on silence. A message that is
queued_behind will simply queue twice, and now you have two copies of the same
request.
The fleet looks busy but nothing is progressing
Cause: liveness is not progress. Output scrolling, a live process, and a non-empty roster are all compatible with zero work happening.
Safe diagnostic
nala tasks list
Expected evidence: task state, which is the honest signal.
WARNING
The fleet roster can report more agents live than actually exist. Confirm against task state before concluding anything about capacity. See known limitations.
Agents will not talk to each other at all
Likely cause: A2A mode.
| Mode | Effect |
|---|---|
Off | No agent messaging |
Connect | Agents may message |
Orchestrate | Agents may coordinate work |
Found in Settings → Agents / Harmony. If you did not set it deliberately, check it — a
workspace in Off produces exactly the symptom of messages going nowhere.
A channel mention never reached its target
Likely cause: the target is scoped to a different workspace.
NOTE
Cross-workspace mention delivery has a known open defect. A mention raised in one workspace may not reach a member scoped to another. This is a product limitation, not a configuration error.
Repair: message the agent directly rather than by channel mention, or keep collaborating agents in one workspace.
Delivery state says unknown
This is not a failure. The classifier reports from observable evidence and declines to guess when there is none.
Repair: look at the agent directly — if it is a provider pane, read the pane.
When not to retry: do not treat unknown as failed and re-send. You may
duplicate work that is actually in progress.
A delegated task never completes
Separate the three questions, because they have different answers:
| Question | Answered by |
|---|---|
| Did the message arrive? | Delivery state |
| Did a turn start? | received_and_started specifically |
| Is the work done? | Task state |
All three can disagree, and usually the gap between the second and third is where the real problem is.
Remote messages appear but do nothing
Expected. Messages arriving from peer machines over LAN Link render as text only. They are never pasted into a PTY and never routed to an execute path.
That is a security boundary, not a bug — a peer cannot make your machine run a command by messaging you.
Collecting evidence
nala doctor --json
nala agent list
nala tasks list
WARNING
Review before sharing. Diagnostics contain absolute paths, workspace and repository names, and message metadata.