Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
246 lines (174 loc) · 4.91 KB

TROUBLESHOOTING.md

File metadata and controls

246 lines (174 loc) · 4.91 KB

Troubleshooting Guide

Solutions for common MemoryGraph issues.

Quick Diagnostics

# Check installation
which memorygraph
memorygraph --version

# Verify configuration
memorygraph --show-config

# Check MCP status in Claude Code
claude mcp list

Common Issues

Command not found: memorygraph

# If using pipx
pipx ensurepath
# Then restart your terminal

# If using pip, check if Python bin is in PATH
python3 -m pip show memorygraphMCP | grep Location

# Find the executable
python3 -c "import shutil; print(shutil.which('memorygraph') or 'Not in PATH')"

# Option 1: Add to PATH (bash)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Option 2: Add to PATH (zsh)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Option 3: Use full path in MCP config
claude mcp add --transport stdio memorygraph -- /full/path/to/memorygraph

MCP Server Connection Failed

If claude mcp list shows "Failed to connect":

# 1. Test the MCP server manually
echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}},"id":1}' | memorygraph

# 2. If you see "AttributeError: 'NoneType' object..."
# You have an old version. Upgrade:
pipx upgrade memorygraphMCP

# 3. Check which version is being used
which memorygraph
memorygraph --version

# 4. Verify pipx installation
pipx list | grep -A 3 memorygraph

Multiple Installation Conflict

When global upgrade doesn't take effect:

# Problem: Project venv has old cached version

# Check project venv version
pip show memorygraphMCP

# Solution 1: Update project installation
cd ~/your-project
pip uninstall -y memorygraphMCP
pip install -e .

# Solution 2: Use full path in MCP config (recommended)
# Find your pipx path:
which memorygraph  # outside any venv

# Update MCP config to use full path:
# "command": "/Users/yourname/.local/bin/memorygraph"

Server won't start

# Check configuration
memorygraph --show-config

# Enable debug logging
MEMORY_LOG_LEVEL=DEBUG memorygraph

# Verify database connection
memorygraph --health

SQLite database locked

# Check for running processes
ps aux | grep memorygraph

# Kill stale processes
pkill -f memorygraph

# Remove lock file if safe
rm ~/.memorygraph/memory.db-lock

# Restart Claude Code

Neo4j connection refused

# Verify Neo4j is running
docker ps | grep neo4j

# Test connection manually
cypher-shell -a bolt://localhost:7687 -u neo4j -p your-password

# Check credentials
memorygraph --backend neo4j --show-config

# Check Neo4j logs
docker logs neo4j-container

Memgraph connection issues

# Verify Memgraph is running
docker ps | grep memgraph

# Test connection
mgconsole --host 127.0.0.1 --port 7687

# Check Memgraph logs
docker logs memgraph-container

FalkorDBLite issues

libomp error on macOS:

# Error: Library not loaded: libomp.dylib
brew install libomp

# Restart your terminal after installation

Database file permissions:

# Check permissions
ls -la ~/.memorygraph/falkordblite.db

# Fix permissions if needed
chmod 644 ~/.memorygraph/falkordblite.db

Import error:

# Install FalkorDBLite
pip install "memorygraphMCP[falkordblite]"

# Verify installation
python -c "import falkordblite; print('FalkorDBLite installed')"

FalkorDB connection issues

Connection refused:

# Verify FalkorDB is running
docker ps | grep falkordb

# Check if port is accessible
nc -zv localhost 6379

# Check FalkorDB logs
docker logs falkordb

# Restart FalkorDB if needed
docker restart falkordb

Wrong host/port:

# Verify configuration
memorygraph --show-config | grep FALKORDB

# Test connection manually
redis-cli -h localhost -p 6379 ping

Import error:

# Install FalkorDB client
pip install "memorygraphMCP[falkordb]"

# Verify installation
python -c "import falkordb; print('FalkorDB client installed')"

Import/Export issues

# Export memories to backup
memorygraph --export backup.json

# Import to new backend
memorygraph --backend neo4j --import backup.json

# Verify import
memorygraph --backend neo4j --show-config

MCP Configuration Issues

Server appears in list but tools don't work

  1. Check that server shows "Connected" in claude mcp list
  2. Restart Claude Code completely (exit and restart)
  3. Check for permission issues in settings

Tools not appearing

# Verify profile setting
memorygraph --show-config | grep profile

# Core mode: 9 tools
# Extended mode: 11 tools
# Extended mode: 11 tools

Getting Help

  1. Check logs: MEMORY_LOG_LEVEL=DEBUG memorygraph
  2. Verify config: memorygraph --show-config
  3. GitHub Issues: Report bugs
  4. Discussions: Ask questions