Troubleshooting

​

Context is empty

Empty context can be the correct result. Inspect mode, delivery, and reason from getContext together. 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.

​

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 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.