This comprehensive guide covers common issues, their causes, and step-by-step solutions for DeepWiki-Open deployment and usage.

Quick Diagnostic Checklist

Before diving into specific issues, run through this quick diagnostic checklist:
1

Check System Status

# 1. Backend API health
curl http://localhost:8001/health

# 2. Frontend accessibility  
curl http://localhost:3000

# 3. Environment variables loaded
python -c "import os; print('Google:', bool(os.getenv('GOOGLE_API_KEY'))); print('OpenAI:', bool(os.getenv('OPENAI_API_KEY')))"

# 4. Process status
ps aux | grep -E "(python.*api|node.*next)"
All services running and responding correctly
2

Review Recent Logs

# Backend logs
tail -50 ./api/logs/application.log

# Docker logs (if using Docker)
docker-compose logs --tail=50

# System logs
journalctl -u deepwiki --since "1 hour ago"
Look for error patterns, failed requests, or configuration warnings
3

Test Basic Functionality

# Test simple wiki generation
curl -X POST "http://localhost:8001/wiki/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_url": "https://github.com/octocat/Hello-World",
    "model_provider": "google"
  }'
Basic functionality working as expected

Installation Issues

Python Installation Problems

Node.js and Frontend Issues

API and Service Issues

API Connection Problems

AI Provider Issues

Wiki Generation Issues

Generation Failures

Quality Issues

Performance Issues

Slow Generation Speed

Docker Issues

Container Problems

Advanced Troubleshooting

Debug Mode

1

Enable Debug Logging

LOG_LEVEL=DEBUG
LOG_FILE_PATH=./api/logs/debug.log
2

Verbose API Output

# Start API with debug output
DEBUG=1 PYTHONPATH=. python -m api.main

# Or with uvicorn directly
uvicorn api.api:app --host 0.0.0.0 --port 8001 --log-level debug
3

Frontend Debug Mode

# Next.js debug mode
DEBUG=* npm run dev

# Or with detailed logging
NODE_OPTIONS='--inspect' npm run dev

Performance Profiling

import cProfile
import pstats

# Profile wiki generation
pr = cProfile.Profile()
pr.enable()

# Your generation code here
generate_wiki(repo_url, model_provider)

pr.disable()
stats = pstats.Stats(pr)
stats.sort_stats('cumulative').print_stats(20)

Getting Help

Collect Debug Information

Before seeking help, collect this information:
1

System Information

# Create debug report
cat > debug_report.txt << EOF
=== System Information ===
OS: $(uname -a)
Python: $(python --version)
Node: $(node --version)
Docker: $(docker --version)

=== Environment ===
$(env | grep -E "DEEPWIKI|GOOGLE|OPENAI" | sed 's/=.*$/=***/')

=== Process Status ===
$(ps aux | grep -E "python.*api|node.*next")

=== Port Status ===
$(netstat -tulpn | grep -E ":8001|:3000")

=== Recent Logs ===
$(tail -50 ./api/logs/application.log)

=== Error Messages ===
$(grep -i error ./api/logs/application.log | tail -20)
EOF
2

Minimal Reproduction

Create a minimal example that reproduces the issue:
# Test with small, public repository
curl -X POST "http://localhost:8001/wiki/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_url": "https://github.com/octocat/Hello-World",
    "model_provider": "google"
  }'

Community Resources

When reporting issues, please include:
  • Your debug report
  • Steps to reproduce the issue
  • Expected vs actual behavior
  • Screenshots or log excerpts
  • Your DeepWiki version and environment

Next Steps