> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Find the boundary that failed before changing models or retrying an operation.

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

| Symptom | Check | Next action |
| - | - | - |
| An export or option is missing | Published package versus current working-tree docs | Follow [installation](/learn/installation); use matching builds |
| Cannot find a provider or database SDK | Optional dependency for that adapter | Install the dependency listed in its integration guide |
| ESM or top-level await error | Project module type and TypeScript runner | Use `type: module` and the [quickstart](/quickstart) commands |
| `Agent.deep` is unavailable | Removed API | Follow [migration](/migration-v4) |
| Workspace configuration is rejected | Explicit access mode | Use an object with `path` and `mode` |

## 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](/ship/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](/ship/operations) explains the diagnostic signals to retain.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.