Troubleshooting. The shortlist.

401 Unauthorized

• Confirm OCTA_API_KEY is set in the environment your process actually reads.
• Check the prefix: oct_live_ for production, oct_test_ for sandbox. Mismatched prefixes are a common copy-paste accident.
• Confirm the key isn’t revoked, rotate from Settings → API keys at platform.octamem.com.
• For browser code: don’t embed live keys client-side. Mint a short-lived session key server-side and pass that down.

Recall returns no records

The most common cause is a scope mismatch between the writer and the reader. scope is hierarchical and case-sensitive.

• recall(scope="acme") matches everything under acme/*.
• recall(scope="acme/launch") only matches acme/launch and below.
• recall(scope="Acme/launch") does not match acme/launch.

Run a wide-scoped recall to confirm the record exists at all:

octa.recall(query="*", limit=20)

429 Rate limited

• The response carries Retry-After in seconds. Honor it.
• Inspect your plan’s rate budget via GET /api/memory/details or octa.account.details().
• For batch backfill, prefer the POST /api/memory/add endpoint, one HTTP call, one rate-limit decrement, hundreds of records.

MCP server doesn’t appear in client

• Restart the client after editing config files. Claude Desktop and Cursor both cache MCP server lists at startup.
• Confirm config file path. macOS Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json.
• Check the bearer token, a 401 from MCP looks like “server didn’t connect” in some clients.
• For older Claude Desktop (no remote MCP support), use the local Node bridge, see Claude Desktop.

CORS errors from the browser

OctaMem doesn’t allow browser-origin direct calls with live keys. Mint short-lived session keys from your server.

// On your server.
const session = await octa.sessions.create({
  scope: "acme/sales",
  ttl_seconds: 3600,
  permissions: ["recall"],
});

// Pass session.token to the browser.
return Response.json({ token: session.token });

“But I want vector search”

OctaMem isn’t a vector database, but it plays well with one. We hold typed memory records with provenance, and recall ranks across typed memory, not raw text. If you already have a vector index, run it alongside OctaMem and pass the vector hits as sources when you call remember. Vectors stay your index. OctaMem stays your record of truth.

Check status

For platform-wide issues, email [email protected]. We confirm incidents and share updates until resolution.