Troubleshooting¶

Common issues, solutions, and debugging guides for KGraph-MCP development and deployment.

🚨 Common Issues¶

Installation Issues¶

Python Version Compatibility¶

# Error: Python version not supported
# Solution: Install Python 3.11.8+
just setup  # Automatically installs correct Python version

Package Installation Failures¶

# Error: Failed to install dependencies
# Solution: Clear cache and reinstall
just clean-all
just setup

Permission Errors¶

# Error: Permission denied during setup
# Solution: Check file permissions
chmod +x justfile
sudo chown -R $USER:$USER .

Development Issues¶

Import Errors¶

# Error: ModuleNotFoundError
# Solution: Ensure virtual environment is activated
source .venv/bin/activate
just install  # Reinstall dependencies

Type Checking Failures¶

# Error: mypy type checking failed
# Solution: Fix type annotations
just type-check  # See specific errors

Linting Errors¶

# Error: Ruff linting failed
# Solution: Auto-fix most issues
just lint  # Automatically fixes issues
just format  # Format code

Documentation Issues¶

MkDocs Build Failures¶

# Error: MkDocs build failed
# Solution: Validate and fix configuration
just docs-validate  # Check for issues
just docs-serve     # Test locally

Missing Dependencies¶

# Error: Plugin not found
# Solution: Install documentation dependencies
uv pip install -r requirements-dev.txt

Broken Links¶

# Error: Link validation failed
# Solution: Check and fix internal links
# Use relative paths: ../section/page.md

🔧 Development Environment Issues¶

Virtual Environment Problems¶

Environment Not Found¶

# Recreate virtual environment
rm -rf .venv
just setup

Package Conflicts¶

# Clear and reinstall all packages
just clean
just update

Git Issues¶

Pre-commit Failures¶

# Fix pre-commit issues
just pre-commit  # Run checks
git add .        # Stage fixes
git commit -m "fix: resolve pre-commit issues"

Branch Management¶

# Clean up merged branches
just branch-cleanup

🌐 Application Issues¶

Server Startup Problems¶

Port Already in Use¶

# Error: Port 8000 already in use
# Solution: Kill existing process or use different port
lsof -ti:8000 | xargs kill -9
# Or specify different port
uvicorn app:app --port 8001

Missing Environment Variables¶

# Create .env file from template
cp .env.example .env
# Edit .env with your configurations

Gradio Interface Issues¶

UI Not Loading¶

# Check if server is running
curl http://localhost:7860
# Restart application
just dev

WebSocket Errors¶

# Clear browser cache and reload
# Check firewall settings
# Ensure port 7860 is accessible

📊 Performance Issues¶

Slow Response Times¶

Database Performance¶

# Check database connections
# Monitor query performance
just stats  # View system statistics

Memory Usage¶

# Monitor memory usage
just profile-memory
# Or use system monitor
top -p $(pgrep -f "python app.py")

High CPU Usage¶

# Profile CPU usage
just monitor
# Check for infinite loops or heavy computations

🔍 Debugging Techniques¶

Enable Debug Logging¶

# Add to app.py
import logging
logging.basicConfig(level=logging.DEBUG)

Use Development Mode¶

# Run with debug enabled
APP_ENV=development just dev

Test Individual Components¶

# Test specific functionality
just test-file tests/test_specific.py

📋 Error Messages & Solutions¶

Common Error Patterns¶

Error Pattern	Likely Cause	Solution
`ModuleNotFoundError`	Missing package or wrong Python path	`just install`
`Permission denied`	File permission issues	`chmod +x` or `sudo chown`
`Port already in use`	Another process using port	Kill process or use different port
`Connection refused`	Server not running	Start server with `just dev`
`Import error`	Virtual environment not activated	`source .venv/bin/activate`

System Requirements Check¶

# Verify system requirements
python --version   # Should be 3.11.8+
node --version     # Should be 16+
git --version      # Should be 2.0+

🆘 Getting Help¶

Self-Help Resources¶

Check this troubleshooting guide
Review the FAQ
Search existing GitHub Issues
Check the Developer Guide

Community Support¶

GitHub Issues: Report bugs and request features
Discussions: GitHub Discussions

Information to Include¶

When reporting issues, please include: - Operating system and version - Python version (python --version) - Error messages (full stack trace) - Steps to reproduce - Expected vs actual behavior

Installation Guide - Setup instructions
Developer Guide - Development setup
API Reference - API documentation
FAQ - Frequently asked questions

This page is part of the Resources documentation section.