> ## Documentation Index
> Fetch the complete documentation index at: https://usereflect.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.

Distinguish three separate events: a context decision arrived, your harness used
it in a model request, and a final trace was accepted for analysis. Success at one
does not prove the others. Compare your hooks with
[agent harness integration](https://usereflect.dev/docs/guides/agent-harness.md).

## Context is empty

Empty context can be the correct result. Inspect `mode`, `delivery`, and `reason`
from TypeScript's `getContext` or Python's `get_context` 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 the SDK's background worker and deployed package files. |
| `invalid_snapshot` (TypeScript) or `invalid_evidence` (Python) | Check canonical message structure, IDs, fixed metadata and snapshot size. |
| `forked_process` (Python) | Construct a fresh client inside each worker process after forking. |
| `canceled` delivery | Preserve the application's abort handling; do not start the model after cancellation. |

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.

## Context arrives but the model does not receive it

Both retrieval methods return a result object with a `context` string; they do not
patch the provider request. At your prompt assembly boundary, append nonempty
`result.context` to a copy of the base system prompt and pass that copy to the
existing model request. Check that a later prompt builder does not overwrite it.
Use a local fake model to inspect the outgoing request without sending private
history to a new endpoint.

Do not store the augmented system prompt as original history. Reusing it on later
turns can duplicate a correction and teach Reflect from its own injected text.
Rebuild each turn from original instructions and retrieve context for that turn.

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

Send a final snapshot after the **execution** ends, including the final response and
tool results. A chat may continue for many turns; do not wait for the user to close
it. For streaming, finalize in the actual stream completion, failure or cancellation
hook, after available original messages have been recorded. Inspect your history mapping and
check the trace format and size limits in [trace capture](https://usereflect.dev/docs/guides/trace-capture.md).

## Captures conflict or later turns replace the wrong trace

Use one execution ID for a run's snapshots and a fresh ID for the next run. Never
reopen a finalized ID after a restart. A `terminal_conflict` receipt can indicate
changed evidence or a changed terminal status after finalization; do not repeatedly
submit a different final snapshot under the same ID.

For a continuing chat, keep its `conversationId` stable and allocate a higher
`conversationRevision` in durable storage before each new run. Keep that pair fixed
within the run. Using a message count, timestamp or process counter can break
ordering. Distinct branches need distinct conversation IDs. See
[conversation identity](https://usereflect.dev/docs/guides/trace-capture.md#conversation-identity).

## 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.
Use the API origin without `/v1` or a runtime route; the SDK supplies those paths.
The SDK requires HTTPS except for local loopback development.

## Retrieval adds more delay than expected

Call `getContext` or `get_context` 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` (TypeScript) or `elapsed_ms` (Python).
Scheduling delays can extend observed deadlines. In async Python, use
`await aget_context(...)` so retrieval does not block the application's event loop.

## Shutdown loses pending captures

Drain during explicit shutdown before `dispose()`:

* **TypeScript:** `await reflect.flush({ timeoutMs: 2000 })`. `complete: true`
  means none of the covered tickets remain pending, even if some were dropped or
  unconfirmed.
* **Python:** `reflect.flush(timeout_ms=2000)` or `await reflect.aflush(timeout_ms=2000)`.
  `.complete` is true only if all covered tickets were accepted, or there were none.

Inspect all returned counts. Both SDKs cover only tickets pending when flush began;
retain individual receipts for earlier deliveries. Abrupt termination can still
lose in-memory work. For a short-lived worker, finish the run's stream and tools,
submit its final capture, then drain within the host's available shutdown time.
See the [Python quickstart](https://usereflect.dev/docs/quickstart-python.md) and
[Python SDK reference](https://usereflect.dev/docs/sdk/python-reference.md) for its source installation and lifecycle.

For help, email [devs@runreflect.com](mailto:devs@runreflect.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.