Troubleshooting
Connection Issues
”401 Unauthorized”
Your API key is missing, malformed, or not found.
- Check that the
Authorizationheader is set:Bearer engram_sk_live_... - Verify the key prefix is
engram_sk_live_(notengram_sk_test_or something else) - Ensure the key hasn’t been revoked
- Keys are case-sensitive — copy the full key exactly as shown at creation
”403 Forbidden”
Your API key exists but is expired or revoked.
- Check if the key has an expiration date that has passed
- Check if the key was revoked by an admin
”Conversation not found”
The conversation ID doesn’t exist or belongs to a different organization.
- Verify the
conv_prefixed ID is correct - Each API key is scoped to one organization — you can’t access conversations from a different org
Search Issues
Search returns no results
- Messages need to be appended via
append_messagesto be indexed. Messages aren’t searchable until they’ve been chunked and embedded. - If you just appended messages, there may be a brief delay for Vectorize indexing (typically less than 1 second).
- Check that you’re searching within the correct organization (API key scope).
- If filtering by
conversation_idortags, verify those filters match existing data.
Search results seem irrelevant
- Semantic search works on meaning, not keywords. “authentication error” will match “login failed” even though they share no words.
- Try rephrasing your query in natural language.
- Use more specific queries for better results.
- Reduce the
limitto get only the highest-confidence matches.
Search doesn’t find recent messages
Messages are chunked in windows of 5. If you’ve appended fewer than 5 messages to a conversation, they’ll still be chunked and searchable, but short conversations may produce lower-confidence matches.
Data Issues
Messages appear out of order
Messages are ordered by sequence number, not by timestamp. If messages appear out of order, check the sequence values in the response.
Sequence numbers are assigned automatically based on the order messages appear in the messages array of append_messages. They’re always sequential within a conversation.
Tags or metadata not showing up
Tags and metadata are stored as JSON strings in D1. When retrieved via get_conversation or list_conversations, they’re parsed back into arrays/objects. If tags appear as a string like "[\"tag1\"]", there may be a double-encoding issue.
Can’t delete a conversation
delete_conversation cascades: it removes the conversation, all its messages, all chunks, and all vectors from the search index. If it returns “Conversation not found”, verify the ID and that it belongs to your organization.
Build errors
# Clean install
rm -rf node_modules
pnpm install
# Build all packages
pnpm build
# Check types
pnpm typecheckThe build order matters: @getengram/shared must build before @getengram/db, which must build before @getengram/mcp-server. Turborepo handles this automatically with pnpm build.