Troubleshooting

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

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

Collect the request id

Copy e.request_id from any SDK exception. It is safe to share.

Note the timestamp

Give us the approximate UTC time the call failed.

Describe the call

Include the method (recall, remember, etc.), session_id, and whether you hit REST or the SDK.

Add version + redact secrets

Run python -c "import tex; print(tex.__version__)". Scrub API keys or PII before you press send.

You can email support@getmetacognition.com or open an issue on GitHub.

Copy-paste diagnostics

# 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.
Identical queries, tiny score deltas: expect minor movement; large swings merit a ticket.

Get started

Concepts

Cookbook

Evaluation

Migration

Support

Match your symptom

Extra

Auth still failing after you rotated keys

You see hits but they feel unrelated

Confidence swings between identical queries

Filing a ticket

Copy-paste diagnostics

Things that look like bugs but are not

​Match your symptom

​Extra

​Auth still failing after you rotated keys

​You see hits but they feel unrelated

​Confidence swings between identical queries

​Filing a ticket

​Copy-paste diagnostics

​Things that look like bugs but are not

Match your symptom

Extra

Auth still failing after you rotated keys

You see hits but they feel unrelated

Confidence swings between identical queries

Filing a ticket

Copy-paste diagnostics

Things that look like bugs but are not