# A2A troubleshooting Source: https://docs.ideharmony.com/a2a/troubleshooting 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.** ```powershell harmony agent delivery-status ``` Five of the six states mean work has not begun. See [delivery lifecycle](/docs/a2a/delivery-lifecycle). --- ## I sent a message and nothing happened **Likely causes, in order of how often they are the answer** 1. `needs_enter` — the text reached the agent's composer and was never submitted. 2. `queued_behind` — accepted, waiting behind other work. 3. `idle` — the agent is at an empty prompt, which usually means your message never arrived at all. 4. 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** ```powershell harmony 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](/docs/reference/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 ```powershell harmony doctor --json harmony agent list harmony tasks list ``` > [!WARNING] > Review before sharing. Diagnostics contain absolute paths, workspace and > repository names, and message metadata. ## Related - [Delivery lifecycle](/docs/a2a/delivery-lifecycle) - [A2A from the CLI](/docs/a2a/cli) - [Channels](/docs/a2a/channels)