Troubleshooting

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

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

1. Collect the request id

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

2. Note the timestamp

   Give us the approximate UTC time the call failed.

3. Describe the call

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

4. Add version + redact secrets

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

You can email [e-mail] 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.