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

# Troubleshooting

> Diagnose empty context, missing traces, configuration problems, and shutdown.

## Context is empty

Empty context can be the correct result. Inspect `mode`, `delivery`, and `reason`
from `getContext` together.

| Observation | What to check |
| - | - |
| Shadow or off mode | Empty context is expected. Review the configured agent mode. |
| `mode_unknown` or `mode_expired` | The SDK does not have a current mode observation. Check connection settings, key permissions, and connectivity. |
| An accepted result without context | Inspect the server reason. A valid no-match is different from a transport fallback. |
| `timeout` or `transport` | Check reachability and added turn latency. Preserve the original prompt rather than retrying indefinitely. |
| `superseded` | A newer request or changed evidence invalidated the pending retrieval for this trace. |
| `capacity` | Reduce concurrent context waits or inspect execution lifecycle cleanup. |
| `worker_failed` | Check worker packaging in your deployed application. |

The first retrieval may return empty while the mode heartbeat starts. Do not add a
blocking startup wait solely to force nonempty context. The API must support the
SDK's mode and context endpoints; an older service may produce fallback results.

## Traces do not appear

Check the capture ticket's receipt. A dropped receipt has a local reason, such as
invalid or oversized evidence. An unconfirmed receipt means delivery is uncertain.
An accepted final capture with ingestion `queued` means processing is pending.
If ingestion is `unsupported_history`, no analysis job was created. Check for
unsupported media or provider-executed tools, empty history, and missing or invalid
tool-call/result associations. Preserve the original evidence rather than inventing
missing associations or silently removing unsupported content.

Make sure you send a final snapshot after the conversation actually ends, including
the final response and tool results. Inspect your original-history mapping and
check the trace format and size limits in [trace capture](/docs/guides/trace-capture).

## Connection settings are rejected

Copy settings from **Agent setup → SDK connection settings**. Use the generated
agent ID, an agent-scoped key with `runtime:read` and `runtime:write`, and the API
URL shown for that agent. Do not use the marketing URL or the agent display name.
The SDK requires HTTPS except for local loopback development.

## Retrieval adds more delay than expected

Call `getContext` once at the chosen user-turn boundary. Repeated calls at internal
tool steps each have their own wait budget. Measure end-to-end turn latency as well
as `elapsedMs`; the JavaScript event loop can delay deadline timers.

## Shutdown loses pending captures

Await `flush({ timeoutMs: 2000 })` during explicit shutdown before `dispose()`.
Inspect the returned counts for pending, dropped, or unconfirmed deliveries.
Flush only covers tickets already pending when it began. Abrupt process termination
can still lose in-memory work.

For help, email [devs@runmirrors.com](mailto:devs@runmirrors.com) with your SDK
version, a minimal reproduction, and redacted result fields. Do not include API
keys or private conversation content in an initial support message.


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