> ## Documentation Index
> Fetch the complete documentation index at: https://metacognition-fdc534de-master.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Match an error or symptom, apply the fix, and collect the right details for support.

<Note>
  Start with the symptom table. Find the error or behavior you see, then try the fix in the same row.
</Note>

## Match your symptom

| Symptom                                              | Likely cause                                                       | Fix                                                                                                                           |
| ---------------------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `AuthenticationError: Invalid API key` on first call | Wrong key, revoked key, or wrong `base_url`                        | Mint a fresh key in the [dashboard](https://app.getmetacognition.com); confirm `TEX_BASE_URL` points to the right environment |
| `BadRequestError: 'scope' field required`            | Raw REST call without the fields the SDK normally adds             | Use the SDK, or include `scope: {org_id, session_id}` yourself in the JSON body                                               |
| `recall` returns zero hits                           | Brand-new session, enrichment still catching up, or query mismatch | Wait a second after `remember`; broaden `q`; try `mode="deep"` once to see if signal appears                                  |
| `recall.confidence` looks stuck low                  | Query does not overlap stored content                              | Rephrase closer to the stored wording; raise `top_k`; try `mode="deep"`                                                       |
| `RateLimitError` mid-day                             | Org exhausted daily quota                                          | Wait for **00:00 UTC**, lower `top_k`, or trim noisy writes. See [Usage and billing](/concepts/usage-billing)                 |
| Slow `recall` (> 5s)                                 | `mode="deep"` or cold caches                                       | Default to `mode="active"` in user-facing paths; warm the client on deploy                                                    |
| `httpx.RemoteProtocolError` / HTTP/2 noise           | Middlebox stripped HTTP/2                                          | Instantiate with `Tex(http2=False)`                                                                                           |
| Long `remember` blocks UX                            | You await ingestion on the hot request path                        | Push persistence to a worker. The [FastAPI recipe](/recipes/fastapi#production-tweaks) shows the pattern                      |
| Flaky CI against prod                                | Shared org contention or dirty sessions                            | Give CI its own org and sweep data on a schedule                                                                              |
| Dashboard `last_used_at` looks stale                 | Browser cache                                                      | Hard refresh; the field updates within seconds of real traffic                                                                |

## Extra

### Auth still failing after you rotated keys

SDK clients cache JWTs until expiry. After you deploy a new **`TEX_API_KEY`**, restart workers or recreate the client. That stops them from sending tokens created from the old key. Also confirm **`https://api.getmetacognition.com`** is spelled correctly in staging configs.

### You see hits but they feel unrelated

Recall ranks by **relevance**, not chronological order. Set **`include_timeline=True`** when the model needs time order. If results still look wrong, check that you are using the same **`session_id`** for write and read. [Scopes and multi-tenancy](/concepts/scopes) explains the mapping.

### Confidence swings between identical queries

Small score changes can happen when candidates are close together. If the spread is bigger than **\~0.1**, capture **`request_id`** and file a ticket.

## Filing a ticket

<Steps>
  <Step title="Collect the request id">
    Copy `e.request_id` from any SDK exception. It is safe to share.
  </Step>

  <Step title="Note the timestamp">
    Give us the approximate UTC time the call failed.
  </Step>

  <Step title="Describe the call">
    Include the method (`recall`, `remember`, etc.), `session_id`, and whether you hit REST or the SDK.
  </Step>

  <Step title="Add version + redact secrets">
    Run `python -c "import tex; print(tex.__version__)"`. Scrub API keys or PII before you press send.
  </Step>
</Steps>

You can email `support@getmetacognition.com` or open an issue on [GitHub](https://github.com/metacoglabs).

## Copy-paste diagnostics

```python theme={null}
# 1. Auth works?
tex.usage.today()         # AuthenticationError here means your key or host is wrong

# 2. Round-trip latency?
import time
t0 = time.perf_counter()
tex.recall(q="ping", session_id="diag")
print(f"recall RTT: {(time.perf_counter()-t0)*1000:.0f}ms")

# 3. SDK version
import tex; print(tex.__version__)
```

## Things that look like bugs but are not

* **Hits are not chronological:** relevance ordering is intentional. Use timeline mode when you need chronology.
* **Empty cross-session recall:** sessions are isolated until you design a scope strategy. See [Scopes and multi-tenancy](/concepts/scopes).
* **Identical queries, tiny score deltas:** expect minor movement; large swings merit a ticket.