Copy-Paste Debug Checklists

Universal (Do This First — Always)

[ ] Confirm floor_id is correct and exists
[ ] Confirm user_id is stable (not regenerated per request)
[ ] Confirm API key is correct and loaded
[ ] Confirm environment (dev/stage/prod) is what you think it is
[ ] Confirm SDK version matches API expectations
[ ] Confirm content ingestion actually completed
[ ] Retry the request once (don’t assume freshness)

If any of the above fails, stop here.
Most bugs die at this stage.

Node.js / JavaScript Checklist

If versions don’t match:

Still broken?

Common mistakes:

Using .env locally but not in prod

Running a built bundle that still references old code

Publishing the same npm version twice (npm blocks this silently)

Reality check

If the version number didn’t change, npm will never update.
This is not negotiable.

TypeScript Checklist

If types look wrong:

If errors persist:

Your SDK was generated from an older OpenAPI spec

Do NOT patch types manually

Upgrade the SDK or regenerate it

Hard truth

Type safety ≠ runtime safety.
Validate inputs on your backend.

Python Checklist

Upgrade explicitly:

If it still doesn’t update:

Version number was reused

PyPI rejected the upload

You’re installing into the wrong virtualenv

Reality check

If pip and python point to different paths, nothing else matters.

Java / Maven Checklist

Force refresh:

If Maven still pulls the old version:

Authentication issues?

Check:

<server><id> matches pom.xml

Token is valid

Correct GitHub / repo owner

Blunt truth

Maven errors lie by omission.
Assume auth or cache until proven otherwise.

Conversation / Memory Debug Checklist

[ ] Same user_id used across requests
[ ] Same floor_id used across requests
[ ] Conversation ID reused only when intended
[ ] New topic = new conversation
[ ] No client-side random IDs

If memory feels “wrong”:

You’re probably leaking or rotating IDs

Or expecting the system to forget automatically (it won’t)

Content / Retrieval Debug Checklist

[ ] Content ingestion API returned success
[ ] Content belongs to the queried floor
[ ] Block boundaries are correct
[ ] Query actually needs floor content
[ ] You waited for indexing

Important

Not every question triggers retrieval.
This is intentional.

Environment Mismatch Checklist (Silent Killer)

[ ] Local API key ≠ Prod API key
[ ] Local floor_id ≠ Prod floor_id
[ ] Dev DB ≠ Prod DB
[ ] Staging SDK version ≠ Prod SDK version

If something works locally but not in prod:
👉 Assume environment mismatch first

Nuclear Option (When Nothing Makes Sense)

Do this once, cleanly:

1. Create a brand-new floor
2. Upload one simple piece of content
3. Use a hardcoded user_id
4. Ask one simple question

If that fails:

It’s a real issue

Everything else was noise

Final Brutal Advice

SDKs don’t auto-heal

Version numbers matter more than code

Cache invalidation is 80% of debugging

Memory bugs are usually identity bugs

If you’re guessing — log everything

Universal (Do This First — Always)#

Node.js / JavaScript Checklist#

TypeScript Checklist#

Python Checklist#

Java / Maven Checklist#

Conversation / Memory Debug Checklist#

Content / Retrieval Debug Checklist#

Environment Mismatch Checklist (Silent Killer)#

Nuclear Option (When Nothing Makes Sense)#

Final Brutal Advice#