Troubleshooting

Connection refused / can’t reach the API

Symptoms: SDK throws fetch failed / ECONNREFUSED, CLI hangs on memoturn search.

Diagnosis: wrong base URL, or transient edge connectivity.

Fix:

• Verify your MEMOTURN_API_URL (or SDK baseUrl); the production endpoint is https://api.memoturn.ai.
• Confirm the API is reachable: curl https://api.memoturn.ai/health should return ok.
• Browsers: check DevTools, Network for CORS errors. The dashboard origin must be allowed.

API key returns 401 Unauthorized

Symptoms: 401 Unauthorized on every request, even right after minting a key.

Diagnosis: the key was copied with whitespace, sent without the mt_ prefix, or scoped to a different project.

Fix:

• Keys are shown once at mint time. Copy the entire string including mt_ prefix.
• Send it as Authorization: Bearer mt_…, not X-API-Key, not just the raw key.
• Confirm the key belongs to the project slug you’re calling. Mint a fresh key on the project’s API Keys tab if unsure.

MCP server “not found” in Cursor / Claude Code

Symptoms: the AI assistant says it can’t see Memoturn tools, or the MCP server status shows red.

Diagnosis: stale config, missing env var, or the MCP transport isn’t routing correctly.

Fix:

• Restart the IDE after editing the MCP config; it does not hot-reload.
• For Claude Code, the entry must include command: "npx" and args: ["-y", "@memoturn/cli", "mcp"] plus an env block with MEMOTURN_API_KEY.
• For Cursor, paste the full JSON shown on the Connect tab. Use copy-with-button to avoid stripping a trailing brace.
• Check the IDE’s MCP log for the actual error. A non-zero exit code usually means the API key is missing or invalid.

WebSocket subscription closes immediately

Symptoms: subscribe() opens, then closes within a second; live presence/events never arrive.

Diagnosis: the API key was rejected, the project slug is wrong, or a proxy is dropping the upgrade.

Fix:

• The WebSocket uses the same Authorization: Bearer … header as REST. If your client can’t send headers on WS, use the ?token= query-string fallback documented in the SDK.
• Confirm the slug exists: GET /v1/projects/{slug} should return 200 with the same key.
• Corporate proxies sometimes strip Upgrade: websocket. Try from a different network to rule that out.

Search returns no results even with recorded turns

Symptoms: record_turn succeeds and list_recent_turns shows your data, but search_memory returns [].

Diagnosis: the ingest pipeline (embed + Postgres + Vectorize) hasn’t caught up yet, or the query is too narrow.

Fix:

• Ingest is async. New turns become searchable within a few seconds, but allow up to ~30s on a cold worker.
• Try mode: "auto" first; it fuses dense, lexical, and hot. entities and code modes only return hits when the query matches a symbol or file path.
• If results never appear, check the dashboard Timeline tab to confirm the turn landed.

Hybrid search “hot” leg always empty

Symptoms: Search results show dense + lexical pills but never hot.

Diagnosis: the hot leg only matches against turns the project’s Durable Object has cached in memory, typically the last few hundred turns of an active session.

Fix:

• Run a query while a session is active (heartbeats arriving). Hot is a recency cache, not a long-term index.
• Cold projects warm the hot leg on the first turn after idle. Send a record_turn and retry.

CLI command not found

Symptoms: memoturn: command not found after pnpm install.

Diagnosis: the CLI is a workspace package, or pnpm didn’t link the bin.

Fix:

• Globally: pnpm add -g @memoturn/cli then re-open your shell.
• Per-project: pnpm dlx @memoturn/cli search "…" works without a global install.
• If you cloned the monorepo: pnpm --filter=@memoturn/cli build then node packages/cli/dist/index.js ….

Dashboard shows “Page not found” for a valid project

Symptoms: Project slug exists but /projects/{slug} 404s.

Diagnosis: session cookie was cleared, or the project belongs to a different organization.

Fix:

• Sign in again. Sessions expire; the dashboard returns 404 instead of a generic redirect for clarity.
• Confirm the slug on the projects sidebar; it’s case-sensitive and dash-separated.

Still stuck?

Email support@memoturn.ai with: the request URL, the response status + body, and a redacted snippet of your config. We triage daily.