docs/resources/troubleshooting.md

metadata

title: Troubleshooting
description: Comprehensive troubleshooting guide for KGraph-MCP issues and solutions

Troubleshooting

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

🚨 Common Issues {#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

1. Check this troubleshooting guide
2. Review the FAQ
3. Search existing GitHub Issues
4. 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

🔗 Related Resources

• 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.