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: ensure MEMNEXUS_API_KEY is set in the env 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 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

Tools don't appear in Claude Desktop

Fix:

1. Verify config file location:
   • macOS: ~/.config/claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Check JSON syntax — no trailing commas, proper quoting
3. Ensure npx is in your PATH: which npx
4. Restart Claude Desktop completely (quit and reopen)

Tools don't appear in Cursor

Fix:

1. Verify .cursor/mcp.json exists in your project root
2. Check JSON syntax
3. Reload the Cursor window (Cmd/Ctrl + Shift + P → "Reload Window")

MCP tool calls fail with authentication error

Fix:

1. Check that MEMNEXUS_API_KEY is in the env section of your MCP config
2. Verify the key is valid: mx auth login --api-key <your-key> && mx auth status
3. Make sure the key includes both parts: cmk_live_<id>.<secret>

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