Troubleshooting

Troubleshooting Guide

Common issues when installing or running the MCP Local Memory Service.

Server Won't Start / MCP Handshake Fails

Symptom: your AI client shows an error like MCP server disconnected or Failed to initialize.

Check 1: Node.js Version

node --version   # requires >= 20

The server depends on better-sqlite3 (Node 20+) and the dashboard tooling requires Node 20.19+ (or 22.12+).

Check 2: Installation is Corrupt

npm uninstall -g @vheins/local-memory-mcp
npm install -g @vheins/local-memory-mcp

Check 3: npx Cache Issues

If using npx, clear the cache:

npx clear-npx-cache 2>/dev/null || rm -rf ~/.npm/_npx

Then try again. The first run downloads the package and can take 10-30 seconds.

Check 4: Binary Not Found After Global Install

which local-memory-mcp   # should show a path

If empty, your npm global bin may not be in $PATH:

npm bin -g   # shows the directory
# Add it to your shell profile:
export PATH="$(npm bin -g):$PATH"

---

Dashboard Won't Load

Symptom: localhost:3456 shows connection refused or a blank page.

Check 1: Is the Server Running?

npx @vheins/local-memory-mcp dashboard

You should see a line like:

DASHBOARD_STARTING v0.35.0 on http://localhost:3456

Check 2: Port Conflict

lsof -i :3456   # macOS/Linux
netstat -ano | findstr :3456   # Windows

If something else is using port 3456, kill it or use a different port via the PORT env:

PORT=3457 npx @vheins/local-memory-mcp dashboard

Check 3: Dashboard Opens But Shows No Data

The dashboard loads data from the same SQLite database the MCP server uses. If the MCP server never ran, there's no data yet — create some activity first by using the MCP tools (e.g. memory-write).

---

"Transformers.js" / ONNX Model Errors

Symptom: errors mentioning Transformers.js, ONNX, or all-MiniLM-L6-v2 during search.

Cause: the first time you search, the server downloads the embedding model (Xenova/all-MiniLM-L6-v2) to Hugging Face's cache directory (~/.cache/huggingface/). This requires an internet connection and can take 30-60 seconds.

Fix: ensure internet access on first run. The model is cached locally afterward — subsequent searches are offline and fast. If the download keeps failing, manually download the model to ~/.cache/huggingface/hub/models--Xenova--all-MiniLM-L6-v2/, then restart the server.

---

Database Locked / SQLite Errors

Symptom:

SQLITE_BUSY: database is locked

or

SQLITE_ERROR: no such table: memories

Cause:

• Locked: two processes are accessing the same SQLite file simultaneously (e.g. MCP server + dashboard pointing to the same DB).
• Missing tables: the database wasn't migrated (shouldn't happen in normal flow, but can occur if the DB file is manually corrupted or deleted mid-operation).

Fix:

1. Kill all running local-memory-mcp processes:

   pkill -f local-memory-mcp   # macOS/Linux

2. Delete the database to start fresh (your data will be lost). The default location depends on your OS:

   # Linux
   rm -f ~/.config/local-memory-mcp/memory.db
   # macOS
   rm -f ~/Library/Application\ Support/local-memory-mcp/memory.db
   # Windows (PowerShell)
   Remove-Item ~/.local-memory-mcp/memory.db

   Note: a legacy ./storage/memory.db in the working directory takes priority if it exists.

3. Restart the server — tables are auto-created on startup.

---

"Memory not found" / Search Returns Nothing

Check 1: Are You Using the Correct Repo?

Memories are scoped to a repository. If your current project is my-app, search for memories in my-app:

{
	"owner": "my-org",
	"repo": "my-app",
	"query": "your search"
}

Check 2: Low Similarity Threshold

Search uses an adaptive threshold: small result sets use a lenient cutoff (0.10), larger sets a stricter one (0.40), and the single best match is always returned even on a cold start. If your query returns nothing, try rephrasing or adding more terms — keyword matching still works for exact terms. See Hybrid Search.

Check 3: Agent Didn't Store Anything Yet

Ask your agent: "What do you remember about this project?" If it says "No memories found," the database is empty — this is normal for a fresh setup.

---

npm/npx Permission Errors

Symptom: Error: EACCES: permission denied

Fix (macOS/Linux): avoid sudo. Instead, fix npm's permissions:

npm config set prefix ~/.npm-global
mkdir -p ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @vheins/local-memory-mcp

Or use a Node version manager like nvm or fnm which avoids permission issues entirely.

---

Agent Says "Tool not found"

Symptom: the AI agent responds with "I don't have a tool called memory-write" or similar.

Cause: the MCP server isn't registered in your client's configuration, or the client didn't restart after configuration was added.

Fix:

1. Double-check your mcpServers JSON matches the Getting Started examples exactly.
2. Restart your AI client completely (not just the conversation).
3. Verify the server appears in the client's MCP server list:
   • Claude Desktop: Click the plug icon → should show "local-memory"
   • Cursor: Settings → MCP → should show "local-memory"
   • Windsurf: MCP configuration panel

---

"EPIPE" or Broken Pipe Errors

Symptom: the server crashes with Error: write EPIPE or stdout is not a TTY.

Cause: the parent process (your AI client) closed the stdio connection unexpectedly. This is usually harmless — the server shuts down when the client disconnects. If it happens repeatedly, the client may be restarting the server too aggressively. Check your client's MCP server keepalive settings.

---

Still Stuck?

• Open a GitHub Issue with:
  • Your OS and Node.js version
  • The exact error message
  • Your MCP client and configuration JSON
• Include logs from stderr (they're usually visible in the client's MCP output panel).

Related Pages

• Getting Started — install and register the server
• Tool Reference & Usage Guide — the 17 tools
• Hybrid Search — search thresholds and ranking
• Panduan Pemecahan Masalah — Bahasa Indonesia