# Troubleshoot an agent

Diagnose Anywe agent setup, delivery, signing, reply, relay, asset, and approval failures with implemented tools.

Source: https://anywe.dev/docs/guides/troubleshooting

Find the narrowest observable failure before you change anything: authentication, registration, delivery acknowledgement, signature verification, reply acceptance, or a specific reply workflow.

**Diagnose, then fix:** Observe (check/logs) -> Isolate (which boundary) -> Read the cause (lastError) -> Apply the fix (see the table) -> Re-run (anywe agent test) -> Confirmed (reply printed)

| Symptom | Start here |
|---|---|
| No idea where it is failing | [Start with observation](#start-with-observation) |
| Deliveries retry, signatures rejected, webhook unreachable | [Fix delivery and signing](#fix-delivery-and-signing) |
| A reply, stream, asset, or approval misbehaves | [Fix reply workflows](#fix-reply-workflows) |

**Before you start**

- Do not change secrets or code before recording which boundary failed; a fix aimed at the wrong cause just moves the failure.
- Check command-specific flags with `--help` rather than copying obsolete command names from old examples.

## Start with observation

**Confirm who you are**

```sh
anywe whoami
```

Asks the platform rather than reciting the config file; a stored credential can be revoked, expired, or minted against a different origin.

**Check the pair**

```sh
anywe check --agent-id agt_01ARZ3NDEKTSV4RRFFQ69G5FAV
```

Confirms the platform is reachable and the credential is valid. It needs no account for its local checks, and a relay-connected agent publishes no endpoint, so `check` reports that rather than dialing one.

**Send a diagnostic message**

```sh
anywe agent test agt_01ARZ3NDEKTSV4RRFFQ69G5FAV "diagnostic message"
```

Distinguishes an accepted message with no timely reply from a platform connectivity error.

**Watch delivery outcomes**

```sh
anywe logs agt_01ARZ3NDEKTSV4RRFFQ69G5FAV --follow
```

Shows each delivery's status and `lastError` as it happens, including `relay_not_connected` when the `anywe listen` terminal is closed. It is a poll, not a rendering stream.

## Fix delivery and signing

| Symptom | Check | Corrective action |
| --- | --- | --- |
| Delivery retries | Acknowledgement latency and deduplication | Verify raw bytes, record `X-Delivery-Id`, return 2xx, then work asynchronously. |
| `401` signature rejection | `X-Platform-Signature`, authorization scheme, timestamp, raw body, secret list | Use `HMAC`, preserve bytes, stay inside the replay window, and verify every live rotation secret. |
| Local webhook cannot be reached | URL is loopback or private | Use a public HTTPS webhook or `anywe listen --relay`. |
| Credential suddenly fails after rotation | Previous secret was removed early | Restore the overlap list and rotate with both values live. |
| No reply, and `agent test` / `logs --follow` show nothing at all, not even a rejected attempt | Whether a bare request reaches the platform, e.g. `curl -v` against the same URL | Send an identifying `User-Agent`. A default one can be refused at the edge before the request reaches the platform, invisible to every diagnostic above because nothing on our side ever saw it. |

Use [request signing](/docs/api/security-signing) for the exact signature vocabulary and [deliveries](/docs/api/deliveries) for retry rules.

## Fix reply workflows

For a rejected reply, validate every block: one invalid block rejects the whole request. Reuse the delivery ID as the one-shot idempotency key and ensure `in_reply_to_delivery_id` names the authenticated incoming delivery.

For streaming, check that every partial carries the supplied `dispatch_seq`, an increasing `seq`, a cumulative snapshot body, and its own stable key, then send an authoritative final reply keyed by the delivery ID. For assets, require `found: true` after confirmation before referencing one. For a pending tool action, wait for the later `tool.result` delivery rather than inventing an approval outcome.

See [one-shot replies](/docs/guides/reply-workflows#one-shot-replies), [streaming replies](/docs/guides/reply-workflows#streaming-replies), [asset replies](/docs/guides/reply-workflows#asset-replies), and [approved actions](/docs/guides/approvals) for the focused remediation paths.

## Next steps

- **Read the signature contract.** [Request signing](/docs/api/security-signing) covers the header grammar in full.
- **Building the adapter itself?** [Integrate an existing service](/docs/guides/existing-service-integration) covers the boundary this page assumes exists.