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) points to your deployed API worker.
• Confirm the API is reachable: curl https://YOUR_API_HOST/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_live_ prefix, or scoped to a different project.

Fix:

• Keys are shown once at mint time. Copy the entire string including the mt_live_ prefix.
• Send it as Authorization: Bearer mt_live_…, not X-API-Key, not just the raw key.
• Confirm the key belongs to the project slug you’re calling. Mint a fresh key under Connect → Credentials 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 host after editing its MCP config; almost none hot-reload.
• Memoturn speaks MCP over streamable HTTP, not stdio. The entry needs type: "http" and a url; there is no command / args form, and @memoturn/cli has no mcp subcommand.
• Confirm the URL includes the project: /v1/projects/<slug>/mcp.
• Copy the snippet from Connect in the dashboard, which fills in your project and endpoint. Use the copy button so a trailing brace isn’t lost.
• Check the host’s MCP log for the actual error. A 401 means the key is missing, revoked, or scoped to another project.

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?

Open an issue at github.com/blakebauman/memoturn with: the request URL, the response status + body, and a redacted snippet of your config.