Troubleshooting

Authentication

"Authentication Error: Invalid or missing API key"

Cause: The API key is missing, malformed, or expired.

Fix:

# Check current auth status
mx auth status

# Re-authenticate
mx auth login --interactive

# Verify it works
mx system health

"401 Unauthorized" on API calls

Cause: The API key isn't being sent correctly.

Fix:

• Verify the key format: cmk_live_<id>.<secret>
• Check the Authorization header: Bearer cmk_live_xxx.yyy
• For SDK: ensure apiKey is set in the client constructor
• For MCP: the bridge reads the key stored by mx auth login — run mx auth status to confirm you're authenticated. No MX_API_KEY env var is needed in the MCP config.

Connection issues

"Connection refused" or "Network error"

Cause: Can't reach the MemNexus API.

Fix:

# Check if the API is reachable
mx system health

# Verify your configured API URL
mx config get apiUrl

# Reset to default
mx config set apiUrl https://api.memnexus.ai

"Request timeout"

Cause: Slow network or API under load.

Fix:

• Check your internet connection
• Try again in a few moments
• For GraphRAG queries, reduce the --max-depth parameter
• For large list operations, use smaller --limit values

Search issues

Search returns no results

Possible causes:

1. No memories stored yet
2. Query doesn't match any memories semantically
3. Topic filters are too restrictive

Fix:

# Check if you have memories
mx memories list --limit 5

# Try a broader search without filters
mx memories search --query "anything"

# Remove topic filters if using them
mx memories search --query "your query"

Search results seem irrelevant

Cause: The query may be too vague or the memories too sparse.

Fix:

• Be more specific: "React state management" instead of "state"
• Add topic filters to narrow scope: --topics "react,frontend"
• Use --timeline mode to see chronological context
• Check memory content — are the stored memories detailed enough?

MCP issues

The MCP integration runs a local bridge, mx mcp serve, which the CLI configures for you. Don't hand-write the config — run mx setup <agent> (for example mx setup claude-desktop or mx setup cursor) and it writes the memnexus server entry. The entry looks like this (agents differ only in the top-level key, e.g. mcpServers, servers, or mcp):

{
  "mcpServers": {
    "memnexus": {
      "type": "stdio",
      "command": "mx",
      "args": ["mcp", "serve"]
    }
  }
}

There is no env block and no API key in this file — the bridge reads your key from the local config written by mx auth login.

Tools don't appear in Claude Desktop, Cursor, or your agent

Cause: The config is missing or malformed, or the agent hasn't been restarted since it was written.

Fix:

1. Run mx setup <agent> to write (or repair) the config.
2. Run mx mcp doctor — it checks auth, the bridge, and each agent's config in one pass and tells you what's wrong.
3. Restart the agent completely (quit and reopen) so it reloads the config.

Config file locations if you need to inspect them:

• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Linux): ~/.config/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• Cursor: .cursor/mcp.json in your project root

If mx setup reports that mx isn't found, install the CLI globally so it's on your PATH: npm install -g @memnexus-ai/cli.

MCP tool calls fail with an authentication error

Cause: The bridge can't find a valid API key. The key comes from your local MemNexus config — written by mx auth login — not from the MCP config file.

Fix:

# Confirm you're authenticated
mx auth status

# If not, log in (stores the key locally)
mx auth login --api-key <your-key>

# Re-run the full MCP health check
mx mcp doctor

The MCP config does not contain your API key. If an older config still has an env block with MX_API_KEY, remove it and re-run mx setup <agent>. Make sure the key includes both parts: cmk_live_<id>.<secret>.

Diagnosing the bridge

Fix:

# Full health check: auth + bridge + agent configs
mx mcp doctor

# Recent bridge log output (connections, reconnects, errors)
mx mcp logs

# Current bridge state (running, stopped, server reachable)
mx mcp status

The bridge logs to ~/.memnexus/logs/mcp-bridge.log. Use mx mcp logs --follow to stream it live. If the bridge appears stuck, mx mcp restart kills the running bridge process so your agent reconnects with a fresh session.

CLI issues

"command not found: mx"

Cause: The CLI isn't installed globally or not in your PATH.

Fix:

# Install globally
npm install -g @memnexus-ai/cli

# Verify installation
mx --version

# If using nvm, ensure the correct Node version is active
nvm use 18
npm install -g @memnexus-ai/cli

JSON parse errors in scripts

Cause: Table format output (the default) isn't valid JSON.

Fix:

# Always use --format json for scripting
mx memories list --format json | jq '.data'

Rate limiting

"429 Too Many Requests"

Cause: You've exceeded the API rate limit.

Fix:

• Wait for the Retry-After period indicated in the response
• Reduce request frequency
• Use pagination with smaller page sizes
• For batch operations, add delays between requests

Getting help

If these solutions don't resolve your issue:

1. Check mx system health for API status
2. Review mx system status for detailed diagnostics
3. Open an issue on GitHub