Troubleshooting

Start with the SDK build, provider configuration, terminal run status, and the earliest failing operation. Remove optional tools and integrations until you have a minimal reproduction.

​

Installation and imports

​

Model and tool execution

No answer or failed run. Check status and provider errors. Verify that the model is available to your account and that the provider received the expected credentials. Do not infer success from a nonempty partial answer. The model does not call a tool. Check that the tool is registered, its description identifies when to use it, the selected provider supports the required tool path, and the prompt contains enough information. Inspect tool events. Instructions influence selection but do not guarantee a call. Tool arguments fail validation. Compare the received arguments with the schema. Keep required inputs explicit. Check that your tool returns a string or ToolResult; an arbitrary object is not the same return contract. A run completes after a denied tool. This can be correct: the final answer explains the denial. Evaluate the action outcome separately from conversation completion. Streaming stops too early. Consume the whole Agent iterator. A model finish chunk can precede a tool roundtrip. Inspect disconnects, cancellation, and buffering limits in the transport.

​

State and retrieval

The agent forgot an earlier message. Compare the session/user scope, confirm that the same store is in use, and check whether the process restarted. In-memory history does not survive a restart. A retrieval answer is unsupported. Inspect the actual retrieved documents before changing the prompt. Verify the indexing/embedding configuration, visibility filter, document freshness, and whether the answer follows the evidence. An attached source ID is not proof of grounding. A session is rejected after authentication. Check the authoritative owner binding and the exact authorization operation. Do not bypass ownership checks to make an error disappear.

​

Timeouts and repeated effects

If a tool contacted an external service before failing, preserve its idempotency key and reconcile the result before retrying. A timeout is not proof that the service did nothing. Follow recovery. For a useful issue report, include the source revision or package versions, Node version, minimal code, expected behavior, terminal status, and redacted error/correlation data. Omit credentials and customer payloads. Operations explains the diagnostic signals to retain.