Diagnose an integration
View SourceStart with the boundary that failed: construction, model admission, tool validation, effect execution, persistence or export. Retain the known progress without turning uncertainty into permission to repeat work.
Common symptoms
| Symptom | Inspect | Next action |
|---|---|---|
| A provider resolves but tools/streaming are rejected | Model protocol, capabilities and explicit profile. | Configure the qualified profile; catalogue membership is insufficient. |
invalid_tool_arguments before invocation | Final arguments envelope, strict JSON, schema and stock diagnostics. | Fix the producer/profile. Preserve the argument gate; do not strip evidence or repair JSON. |
| Output validation fails | Ecto changeset, output mode and remaining request budget. | Fix the output contract or input. Deliver only the successful terminal output. |
Server returns :busy / :queue_full | Active run, pending count and byte bounds via Server.health/1. | Apply application backpressure; queue admission is volatile. |
| An event appears on the wrong screen | Namespace and request ID in ExAgent.Event. | Subscribe to the authenticated topic and match both identifiers. |
| A checkpoint fails | CheckpointError and current dirty state. | Retry the exact storage transition, not the prompt or effect. |
| Restore rejects stored data | Snapshot/record version, ID, policy and model/tool bindings. | Follow migration; do not silently replace it with an empty conversation. |
| A resumed attempt reports uncertainty or an active claim | Current continuation record and external effect evidence. | Recover/reconcile explicitly; do not start a competing fresh run. |
| MCP times out | Request deadline, pool capacity and remote outcome. | Treat the effect as potentially completed; reconnect never means replay. |
| Token/cost totals differ across parent and child spans | Inclusive totals, provenance and completeness. | Read the root once; do not add an inclusive parent to its children. |
Langfuse or Opik shows empty input/output
With default content capture disabled, Input null and Output undefined are
expected. They are not evidence that a model step did nothing. Use the
observation's attributes to inspect run/root/parent IDs, request/tool counters,
status, usage completeness, provenance and estimated cents.
TestModel tokens are synthetic, and estimated cost is not an invoice. A recovery trace can retain an earlier error followed by a valid checkpoint/resume; inspect the operation's place in the tree and its causal outcome. Historical error spans are not erased by later success.
Read Observability before enabling content capture or choosing an export route. Content redaction occurs before transport; the host owns credentials, SDK and exporter lifecycle.
Distinguish test results
An excluded test never executed. Provider and SQL tests require their external systems and explicit configuration. An executing test that reaches its timeout fails. A passing TestModel test establishes local behavior, not provider compatibility. Use Testing to select the relevant boundary.
Report a reproducible problem
Include the package/source version, Elixir/OTP, model/transport profile, a minimal public-API example, the sanitized reason and the relevant partial counters/status. Use TestModel when the issue can be reproduced locally. Include real-backend evidence separately when the failure depends on that backend.
Do not attach a whole live result, error, .env, credential-bearing model or
unredacted trace payload. Application data can contain secrets even when it is
valid JSON.
API: ExAgent.RunError,
ExAgent.Server.health/1,
ExAgent.Continuation.