Troubleshooting Guide¶

This guide helps you diagnose and resolve common issues with the Code Graph Knowledge System.

Table of Contents¶

• Quick Diagnostics
• Connection Issues
• Docker Deployment Issues
• Neo4j Problems
• LLM Provider Issues
• Performance Problems
• Memory Issues
• MCP Server Problems
• API Errors
• Installation Issues
• Data and Storage Issues
• Common Error Messages

Quick Diagnostics¶

Health Check¶

Start with the health check endpoint:

curl http://localhost:8000/api/v1/health

Healthy Response:

{
  "status": "healthy",
  "neo4j": "connected",
  "llm_provider": "ollama",
  "version": "0.7.0"
}

Unhealthy Response:

{
  "status": "unhealthy",
  "neo4j": "disconnected",
  "llm_provider": "error",
  "error": "Connection timeout"
}

System Check Command¶

# Check all services
python -m codebase_rag --check

# Check logs
tail -f logs/application.log

# Check Docker containers
docker ps -a
docker logs code-graph-api
docker logs code-graph-neo4j

Common Issues Quick Reference¶

Connection Issues¶

Neo4j Connection Timeout¶

Symptom:

neo4j.exceptions.ServiceUnavailable: Failed to establish connection to bolt://localhost:7687

Diagnosis:

# Check if Neo4j is running
docker ps | grep neo4j
# or
sudo systemctl status neo4j

# Try connecting manually
docker exec -it code-graph-neo4j cypher-shell -u neo4j -p yourpassword

Solutions:

1. Neo4j not running:

   # Docker
   docker-compose up -d neo4j
   
   # Native
   sudo systemctl start neo4j
   

2. Wrong connection details:

   # Check .env file
   cat .env | grep NEO4J
   
   # Should be:
   NEO4J_URI=bolt://localhost:7687
   NEO4J_USER=neo4j
   NEO4J_PASSWORD=your-password
   

3. Neo4j not ready yet:

   # Wait for Neo4j to fully start (30-60 seconds)
   docker logs -f code-graph-neo4j
   # Look for: "Started."
   

4. Firewall blocking connection:

   # Check port accessibility
   telnet localhost 7687
   nc -zv localhost 7687
   
   # Allow port in firewall
   sudo ufw allow 7687
   

5. Docker network issues:

   # Check network
   docker network ls
   docker network inspect code-graph_default
   
   # Recreate network
   docker-compose down
   docker-compose up -d
   

Ollama Connection Failed¶

Symptom:

httpx.ConnectError: [Errno 111] Connection refused

Diagnosis:

# Check if Ollama is running
curl http://localhost:11434/api/tags
ps aux | grep ollama

Solutions:

1. Ollama not running:

   # Start Ollama
   ollama serve
   
   # Or run in background
   nohup ollama serve > /dev/null 2>&1 &
   

2. Model not downloaded:

   # Check available models
   ollama list
   
   # Pull required models
   ollama pull llama3.2:3b
   ollama pull nomic-embed-text
   

3. Wrong Ollama URL:

   # Check .env
   OLLAMA_BASE_URL=http://localhost:11434
   
   # If Ollama is on different host
   OLLAMA_BASE_URL=http://192.168.1.100:11434
   

OpenAI API Connection Issues¶

Symptom:

openai.error.AuthenticationError: Invalid API key

Solutions:

1. Invalid API key:

   # Check .env file
   cat .env | grep OPENAI_API_KEY
   
   # Get new key from: https://platform.openai.com/api-keys
   OPENAI_API_KEY=sk-your-key-here
   

2. Network connectivity:

   # Test OpenAI connectivity
   curl https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"
   

3. Rate limiting:

   # Wait and retry
   # Implement exponential backoff in code
   # Upgrade OpenAI plan for higher limits
   

Docker Deployment Issues¶

Container Won't Start¶

Symptom:

docker ps -a
# Shows container with status "Exited (1)"

Diagnosis:

# Check container logs
docker logs code-graph-api

# Check all container logs
docker-compose logs

Common Issues:

1. Missing environment variables:

   # Check docker-compose.yml has environment section
   environment:
     - NEO4J_URI=bolt://neo4j:7687
     - NEO4J_USER=neo4j
     - NEO4J_PASSWORD=${NEO4J_PASSWORD}
   
   # Check .env file exists
   ls -la .env
   

2. Port already in use:

   # Check what's using port 8000
   lsof -i :8000  # Linux/macOS
   netstat -ano | findstr :8000  # Windows
   
   # Kill process or change port
   docker-compose down
   # Edit docker-compose.yml to use different port
   ports:
     - "8001:8000"
   docker-compose up -d
   

3. Out of disk space:

   # Check disk space
   df -h
   
   # Clean up Docker
   docker system prune -a
   docker volume prune
   

4. Memory limits:

   # Increase Docker memory
   # Docker Desktop: Settings > Resources > Memory (increase to 4GB+)
   
   # Or in docker-compose.yml
   services:
     api:
       deploy:
         resources:
           limits:
             memory: 2G
   

Docker Compose Errors¶

Error: "Version is not supported"

# Update Docker Compose
sudo apt-get update
sudo apt-get install docker-compose-plugin

# Or use docker compose (without hyphen)
docker compose up -d

Error: "Network not found"

# Recreate network
docker-compose down
docker network prune
docker-compose up -d

Error: "Volume not found"

# List volumes
docker volume ls

# Recreate volumes
docker-compose down -v
docker-compose up -d

Container Networking Issues¶

Containers can't communicate:

# Check network
docker network ls
docker network inspect code-graph_default

# Ensure containers are on same network
docker-compose ps

# Test connectivity
docker exec code-graph-api ping neo4j

DNS resolution fails:

# Use service name, not localhost
NEO4J_URI=bolt://neo4j:7687  # Correct in Docker
NEO4J_URI=bolt://localhost:7687  # Wrong in Docker

Neo4j Problems¶

Neo4j Out of Memory¶

Symptom:

Neo4j heap memory exceeded
OutOfMemoryError: Java heap space

Solutions:

1. Increase heap size:

   # docker-compose.yml
   services:
     neo4j:
       environment:
         - NEO4J_dbms_memory_heap_max__size=4G
         - NEO4J_dbms_memory_pagecache_size=2G
   

2. Clear old data:

   // In Neo4j Browser (http://localhost:7474)
   
   // Delete old nodes
   MATCH (n:Document) WHERE n.created < datetime() - duration('P30D')
   DETACH DELETE n
   
   // Or clear all data (CAUTION!)
   MATCH (n) DETACH DELETE n
   

3. Optimize queries:

   // Add indexes
   CREATE INDEX document_id IF NOT EXISTS FOR (d:Document) ON (d.id)
   CREATE INDEX memory_project IF NOT EXISTS FOR (m:Memory) ON (m.project_id)
   

Neo4j Browser Not Accessible¶

Symptom: Cannot access http://localhost:7474

Solutions:

1. Check port mapping:

   docker ps | grep neo4j
   # Should show: 0.0.0.0:7474->7474/tcp
   
   # If not, check docker-compose.yml
   ports:
     - "7474:7474"
     - "7687:7687"
   

2. Neo4j not ready:

   # Wait for startup
   docker logs -f code-graph-neo4j
   # Look for: "Started."
   

3. Firewall blocking:

   sudo ufw allow 7474
   

APOC Plugin Issues¶

Symptom:

There is no procedure with the name `apoc.meta.data` registered

Solutions:

1. APOC not installed:

   # docker-compose.yml
   services:
     neo4j:
       environment:
         - NEO4J_PLUGINS=["apoc"]
         - NEO4J_dbms_security_procedures_unrestricted=apoc.*
   

2. Restart Neo4j:

   docker-compose restart neo4j
   

3. Verify APOC:

   // In Neo4j Browser
   RETURN apoc.version()
   

Neo4j Authentication Failed¶

Symptom:

Neo4j.ClientError.Security.Unauthorized

Solutions:

# Reset password
docker exec -it code-graph-neo4j cypher-shell -u neo4j -p neo4j
# Follow prompts to change password

# Update .env
NEO4J_PASSWORD=new-password

# Restart application
docker-compose restart api

LLM Provider Issues¶

Ollama Model Not Found¶

Symptom:

Error: model 'llama3.2:3b' not found

Solutions:

# List available models
ollama list

# Pull required model
ollama pull llama3.2:3b
ollama pull nomic-embed-text

# Verify in .env
OLLAMA_MODEL=llama3.2:3b
OLLAMA_EMBEDDING_MODEL=nomic-embed-text

Ollama Out of Memory¶

Symptom:

Error loading model: insufficient memory

Solutions:

1. Use smaller model:

   # 3B model instead of 7B
   ollama pull llama3.2:3b
   
   # Update .env
   OLLAMA_MODEL=llama3.2:3b
   

2. Increase system memory:

3. Close other applications
4. Increase Docker memory limit

5. Use smaller context window

6. Use CPU offloading:

   # Ollama automatically offloads to CPU when GPU memory is full
   # Monitor with:
   ollama ps
   

OpenAI Rate Limit Exceeded¶

Symptom:

openai.error.RateLimitError: Rate limit exceeded

Solutions:

1. Wait and retry:

   # Application has exponential backoff
   # Wait 1 minute and try again
   

2. Upgrade OpenAI plan:

3. Visit OpenAI dashboard
4. Increase rate limits

5. Add payment method

6. Switch to Ollama:

   # No rate limits with local Ollama
   LLM_PROVIDER=ollama
   

Gemini API Quota Exceeded¶

Symptom:

google.api_core.exceptions.ResourceExhausted: Quota exceeded

Solutions:

1. Check quota:
2. Visit Google AI Studio
3. Check daily quota usage

4. Wait for quota reset (midnight Pacific)

5. Request quota increase:

6. Contact Google support
7. Upgrade to paid plan

Performance Problems¶

Slow Query Responses¶

Symptom: Queries take > 30 seconds

Diagnosis:

# Check system resources
top
htop
docker stats

# Check Neo4j query performance
# In Neo4j Browser, run with PROFILE:
PROFILE MATCH (n:Document) RETURN n LIMIT 10

Solutions:

1. Add Neo4j indexes:

   // Create indexes on frequently queried fields
   CREATE INDEX document_content IF NOT EXISTS
   FOR (d:Document) ON (d.content)
   
   CREATE INDEX memory_tags IF NOT EXISTS
   FOR (m:Memory) ON (m.tags)
   
   // Check indexes
   SHOW INDEXES
   

2. Optimize chunk size:

   # In .env
   CHUNK_SIZE=512  # Smaller chunks for faster search
   CHUNK_OVERLAP=50
   

3. Use smaller embedding model:

   # Ollama
   OLLAMA_EMBEDDING_MODEL=nomic-embed-text  # Fast
   
   # OpenAI
   OPENAI_EMBEDDING_MODEL=text-embedding-3-small  # Fast & cheap
   

4. Increase timeouts:

   # .env
   OPERATION_TIMEOUT=600  # 10 minutes
   LARGE_DOCUMENT_TIMEOUT=1200  # 20 minutes
   

High Memory Usage¶

Symptom:

docker stats
# Shows 90%+ memory usage

Solutions:

1. Increase Docker memory:

   # Docker Desktop: Settings > Resources
   # Increase memory to 8GB or more
   

2. Reduce Neo4j memory:

   # docker-compose.yml
   services:
     neo4j:
       environment:
         - NEO4J_dbms_memory_heap_max__size=2G  # Reduce from 4G
   

3. Process documents in batches:

   # Use directory processing with batch size
   # MCP: ingest_directory with smaller batches
   # API: Process files one at a time
   

4. Clear cache:

   # Restart services
   docker-compose restart
   
   # Clear Neo4j page cache
   # In Neo4j Browser:
   CALL dbms.clearQueryCaches()
   

High CPU Usage¶

Symptom: CPU at 100% constantly

Solutions:

1. Check what's consuming CPU:

   docker stats
   # Identify the container
   
   docker top code-graph-api
   

2. Ollama consuming CPU:

   # Normal during inference
   # Use GPU if available
   # Reduce concurrent requests
   

3. Limit concurrent operations:

   # In code, limit concurrent tasks
   # Default: 5 concurrent operations
   MAX_CONCURRENT_OPERATIONS=3
   

Memory Issues¶

Memory Store Search Slow¶

Symptom: Memory search takes > 5 seconds

Solutions:

1. Add fulltext index:

   // In Neo4j Browser
   CREATE FULLTEXT INDEX memory_fulltext IF NOT EXISTS
   FOR (m:Memory)
   ON EACH [m.title, m.content, m.reason, m.tags]
   
   // Verify
   SHOW INDEXES
   

2. Limit search results:

   # When searching, use limit
   search_memories(query="...", limit=20)  # Instead of 100
   

3. Filter by importance:

   # Only search important memories
   search_memories(query="...", min_importance=0.7)
   

Memory Not Found After Adding¶

Symptom: Memory added successfully but search doesn't find it

Diagnosis:

// Check if memory exists
MATCH (m:Memory {project_id: "your-project"})
RETURN m LIMIT 10

// Check memory count
MATCH (m:Memory {project_id: "your-project"})
RETURN count(m)

Solutions:

1. Index not updated:

   // Rebuild fulltext index
   DROP INDEX memory_fulltext IF EXISTS
   CREATE FULLTEXT INDEX memory_fulltext
   FOR (m:Memory)
   ON EACH [m.title, m.content, m.reason, m.tags]
   

2. Search query too specific:

   # Use broader search terms
   # Instead of: "PostgreSQL database configuration"
   # Try: "PostgreSQL" or "database"
   

3. Project ID mismatch:

   # Check project ID is consistent
   echo $PROJECT_ID
   

MCP Server Problems¶

MCP Server Won't Start¶

Symptom:

Error: MCP server failed to start

Diagnosis:

# Try starting manually
python -m codebase_rag --mcp

# Check logs
python -m codebase_rag --mcp 2>&1 | tee mcp.log

Solutions:

1. Missing MCP package:

   uv pip install mcp>=1.1.0
   

2. Port already in use:

   # Check ports
   lsof -i :8001
   
   # Kill process or use different port
   # MCP server uses stdio by default (no port needed)
   

3. Neo4j not accessible:

   # MCP server needs Neo4j
   # Check Neo4j is running
   docker ps | grep neo4j
   

MCP Tools Not Appearing in Claude¶

Symptom: MCP tools don't show up in Claude Desktop

Solutions:

1. Check Claude config:

   # macOS
   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # Should contain:
   {
     "mcpServers": {
       "code-graph": {
         "command": "python",
         "args": ["/path/to/codebase-rag/start_mcp.py"]
       }
     }
   }
   

2. Check MCP server path:

   # Use absolute path
   "args": ["/home/user/codebase-rag/start_mcp.py"]
   
   # Not relative path
   "args": ["./start_mcp.py"]  # Wrong
   

3. Restart Claude Desktop:

   # Completely quit and restart Claude Desktop
   # Check MCP status in Claude: cmd/ctrl + ,
   

4. Check Python environment:

   {
     "mcpServers": {
       "code-graph": {
         "command": "/path/to/.venv/bin/python",
         "args": ["/path/to/start_mcp.py"],
         "env": {
           "PYTHONPATH": "/path/to/codebase-rag"
         }
       }
     }
   }
   

MCP Tool Execution Fails¶

Symptom:

Error executing tool: Connection timeout

Solutions:

1. Increase timeouts:

   # .env
   OPERATION_TIMEOUT=600
   CONNECTION_TIMEOUT=60
   

2. Check Neo4j connection:

   # MCP tools need working Neo4j
   python -c "from neo4j import GraphDatabase; driver = GraphDatabase.driver('bolt://localhost:7687', auth=('neo4j', 'password')); driver.verify_connectivity(); print('OK')"
   

3. Check file paths:

   # Use absolute paths in MCP tool calls
   # Not: "documents/file.txt"
   # Use: "/home/user/project/documents/file.txt"
   

API Errors¶

500 Internal Server Error¶

Diagnosis:

# Check application logs
docker logs code-graph-api

# Or local logs
tail -f logs/application.log

Common Causes:

1. Configuration error:

   # Check .env file
   cat .env
   # Ensure all required variables are set
   

2. Database connection lost:

   # Restart Neo4j
   docker-compose restart neo4j
   

3. Unhandled exception:

   # Check logs for stack trace
   # Report bug with full error message
   

422 Validation Error¶

Symptom:

{
  "detail": [
    {
      "loc": ["body", "memory_type"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Solution: Check your request body includes all required fields.

Example correct request:

curl -X POST http://localhost:8000/api/v1/memory/add \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "myapp",
    "memory_type": "decision",
    "title": "Use PostgreSQL",
    "content": "Selected PostgreSQL as database",
    "importance": 0.8
  }'

404 Not Found¶

Diagnosis:

# Check available endpoints
curl http://localhost:8000/openapi.json | jq '.paths | keys'

Solutions:

1. Check API version:

   # Correct
   curl http://localhost:8000/api/v1/health
   
   # Wrong
   curl http://localhost:8000/health
   

2. Check URL spelling:

   # Correct
   /api/v1/memory/add
   
   # Wrong
   /api/v1/memories/add
   

Installation Issues¶

uv Installation Fails¶

Symptom:

curl: command not found

Solution:

# Install curl first
sudo apt-get install curl  # Debian/Ubuntu
brew install curl  # macOS

# Then install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

Python Version Issues¶

Symptom:

ERROR: This package requires Python 3.13+

Solutions:

# Check Python version
python --version

# Install Python 3.13
## Ubuntu/Debian
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.13

## macOS
brew install python@3.13

# Create venv with correct Python
python3.13 -m venv .venv
source .venv/bin/activate

Dependency Installation Fails¶

Symptom:

ERROR: Could not build wheels for llama-index

Solutions:

1. Install build dependencies:

   # Debian/Ubuntu
   sudo apt-get install build-essential python3.13-dev
   
   # macOS
   xcode-select --install
   

2. Clear cache and retry:

   uv cache clean
   uv pip install -e .
   

3. Use pre-built wheels:

   uv pip install --only-binary :all: -e .
   

Data and Storage Issues¶

Disk Space Full¶

Symptom:

OSError: [Errno 28] No space left on device

Solutions:

# Check disk space
df -h

# Clean up Docker
docker system prune -a
docker volume prune

# Clean up Neo4j data (CAUTION: deletes all data)
docker-compose down -v
docker-compose up -d

# Clean up logs
rm -rf logs/*.log.*

Data Corruption¶

Symptom:

Neo4j database files are corrupted

Solutions:

1. Backup and restore:

   # Stop Neo4j
   docker-compose stop neo4j
   
   # Backup data
   docker cp code-graph-neo4j:/data ./neo4j-backup
   
   # Remove corrupted data
   docker volume rm code-graph_neo4j_data
   
   # Restart and restore
   docker-compose up -d neo4j
   # Re-import your data
   

2. Check disk health:

   # Check for disk errors
   dmesg | grep error
   sudo fsck /dev/sda1
   

Common Error Messages¶

"Cannot connect to Neo4j"¶

• Check Neo4j is running: docker ps | grep neo4j
• Check connection string in .env
• Check network connectivity

"LLM provider not configured"¶

• Set LLM_PROVIDER in .env
• Install provider (Ollama/OpenAI/Gemini)
• Download models if using Ollama

"Memory not found"¶

• Check project_id is correct
• Verify memory exists: MATCH (m:Memory) RETURN m
• Rebuild search index

"Operation timeout"¶

• Increase timeout in .env
• Check system resources
• Process smaller documents

"Permission denied"¶

• Check file permissions: ls -la
• Fix with: chmod +x start.py
• Check Docker permissions: Add user to docker group

"Module not found"¶

• Install dependencies: uv pip install -e .
• Check virtual environment is activated
• Set PYTHONPATH: export PYTHONPATH=$PWD

Getting More Help¶

Collect Diagnostic Information¶

When reporting issues, include:

# System information
uname -a
python --version
docker --version

# Application logs
docker logs code-graph-api > api.log
docker logs code-graph-neo4j > neo4j.log

# Configuration (remove sensitive data!)
cat .env | sed 's/PASSWORD=.*/PASSWORD=REDACTED/'

# Neo4j information
# In Neo4j Browser:
CALL dbms.components()
CALL apoc.version()

Where to Get Help¶

1. Documentation: https://code-graph.vantagecraft.dev
2. GitHub Issues: Search existing issues or create new one
3. GitHub Discussions: Ask questions
4. Discord/Slack: Community chat (if available)

Creating a Good Bug Report¶

Include:

1. Environment: OS, Python version, deployment mode
2. Steps to reproduce: Exact commands and actions
3. Expected behavior: What should happen
4. Actual behavior: What actually happens
5. Logs: Relevant error messages and stack traces
6. Configuration: Sanitized .env file contents
7. Attempts to fix: What you've already tried

Example Bug Report Template¶

## Environment
- OS: Ubuntu 22.04
- Python: 3.13.1
- Deployment: Docker Compose
- Version: 0.7.0

## Issue
Memory search returns no results despite having memories in database.

## Steps to Reproduce
1. Add memory: `curl -X POST ...`
2. Search memory: `curl -X POST ...`
3. Gets empty result: `{"memories": []}`

## Expected Behavior
Should return the memory added in step 1.

## Logs

## Configuration
```env
NEO4J_URI=bolt://neo4j:7687
LLM_PROVIDER=ollama

Attempts to Fix¶

• Restarted Neo4j: No change
• Checked memory exists: Confirmed with Cypher query
• Rebuilt index: Same error ```

Need Immediate Help?¶

For critical production issues:

1. Check Status Page (if available)
2. Rollback to previous version
3. Enable debug logging: LOG_LEVEL=DEBUG
4. Contact maintainers directly
5. Post in #urgent channel (if community exists)

Remember: Most issues are configuration-related. Double-check your .env file and ensure all services are running!