Troubleshooting Guide

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:

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

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

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

Python Version Conflicts

Symptoms:

python: command not found
ImportError: No module named 'fastapi'
Version mismatch errors

Diagnosis:

# Check Python version and location
python --version
python3 --version
which python
which python3

# Check virtual environment
echo $VIRTUAL_ENV
pip list | head -10

Solutions:

Use Python 3 Explicitly
Fix Virtual Environment
Use pyenv (Recommended)

# Create alias (temporary)
alias python=python3
alias pip=pip3

# Or use python3 directly
python3 -m venv venv
source venv/bin/activate
python3 -m pip install -r api/requirements.txt

Dependency Installation Failures

Symptoms:

error: Microsoft Visual C++ 14.0 is required (Windows)
Failed building wheel for numpy
Permission denied errors

Solutions:

Windows
macOS
Linux

# Install Visual Studio Build Tools
# Download from: https://visualstudio.microsoft.com/visual-cpp-build-tools/

# Or use conda instead of pip
conda create -n deepwiki python=3.10
conda activate deepwiki
conda install fastapi uvicorn numpy

# Install remaining packages with pip
pip install -r api/requirements.txt

Node.js and Frontend Issues

Node.js Version Issues

Symptoms:

npm ERR! unsupported engine
React/Next.js compatibility errors
Build failures

Diagnosis:

# Check Node.js and npm versions
node --version
npm --version

# Check package.json requirements
grep -A 5 -B 5 "engines" package.json

# Check installed packages
npm list --depth=0

Solutions:

Update Node.js
Use Yarn Instead
Docker Alternative

# Using Node Version Manager (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 18
nvm use 18

# Verify version
node --version  # Should show v18.x.x

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

npm Permission Errors

Symptoms:

npm ERR! EACCES: permission denied
cannot run in wd errors
Global package installation failures

Solutions:

Fix npm Permissions
Use Node Version Manager

# Set npm global directory to user folder
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH=~/.npm-global/bin:$PATH
source ~/.bashrc

# Reinstall packages
npm install -g npm@latest

API and Service Issues

API Connection Problems

Backend API Not Starting

Symptoms:

Connection refused errors
No response from localhost:8001
FastAPI startup failures

Diagnosis:

# Check if process is running
ps aux | grep python | grep api

# Check port availability
netstat -tulpn | grep 8001
# Or
lsof -i :8001

# Check API logs
tail -f ./api/logs/application.log

# Test direct Python execution
cd api && python main.py

Solutions:

Port Conflicts
Missing Dependencies
Configuration Issues

# Kill process using port 8001
sudo lsof -ti:8001 | xargs sudo kill -9

# Or use different port
export PORT=8002
python -m api.main

# Update frontend configuration
# In .env or next.config.js:
# SERVER_BASE_URL=http://localhost:8002

Frontend Connection Issues

Symptoms:

Frontend loads but can’t connect to API
CORS errors in browser console
Network request failures

Diagnosis:

# Check if frontend is running
curl -I http://localhost:3000

# Check browser console for errors
# Open Developer Tools → Console

# Test API from command line
curl -v http://localhost:8001/health

# Check frontend configuration
grep -r "localhost:8001" src/
grep -r "SERVER_BASE_URL" .

Solutions:

CORS Configuration
API URL Configuration
Network Debugging

# In api/api.py, ensure CORS is configured:
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # In production, specify exact origins
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

AI Provider Issues

API Key Problems

Symptoms:

“Invalid API key” errors
Authentication failures
Provider-specific error messages

Diagnosis:

# Test API keys directly
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
  https://api.openai.com/v1/models

curl -H "Authorization: Bearer $GOOGLE_API_KEY" \
  "https://generativelanguage.googleapis.com/v1/models"

# Check API key format
echo $GOOGLE_API_KEY | grep -E "^AIza[0-9A-Za-z-_]{35}$"
echo $OPENAI_API_KEY | grep -E "^sk-[0-9A-Za-z]{48}$"

Solutions:

Google API Key
OpenAI API Key
Environment Loading

# Verify key is active
curl "https://generativelanguage.googleapis.com/v1/models?key=$GOOGLE_API_KEY"

# Common issues:
# 1. Key not enabled for Generative AI API
# 2. Billing not enabled
# 3. Key restrictions (IP/referrer)

# Fix: Go to Google Cloud Console
# Enable Generative AI API
# Check API key restrictions

Rate Limiting Issues

Symptoms:

“Too many requests” errors
Slow or hanging generation
HTTP 429 responses

Diagnosis:

# Check current usage
curl -s http://localhost:8001/auth/status | jq '.providers'

# Monitor API logs for rate limit messages
tail -f ./api/logs/application.log | grep -i "rate"

# Test with small repository first
curl -X POST "http://localhost:8001/wiki/generate" \
  -d '{"repo_url": "https://github.com/octocat/Hello-World"}'

Solutions:

Adjust Rate Limits
Use Multiple Providers
Optimize Requests

# In api configuration
RATE_LIMIT_CONFIG = {
    "google": {
        "requests_per_minute": 12,  # Under 15 limit
        "retry_delay": 5,
        "backoff_factor": 2
    },
    "openai": {
        "requests_per_minute": 45,  # Under 50 limit  
        "retry_delay": 10
    }
}

Wiki Generation Issues

Generation Failures

Repository Access Issues

Symptoms:

“Repository not found” errors
Private repository access denied
Authentication failures for repositories

Diagnosis:

# Test repository access manually
git clone https://github.com/user/repo.git test-clone
rm -rf test-clone

# For private repos, test with token
git clone https://token@github.com/user/private-repo.git

# Check repository URL format
echo "https://github.com/microsoft/vscode" | \
  grep -E "^https://(github|gitlab|bitbucket)\.(com|org)/.+/.+$"

Solutions:

Public Repository Issues
Private Repository Setup
GitLab/BitBucket

# Verify repository exists and is public
curl -s https://api.github.com/repos/microsoft/vscode

# Check for typos in URL
# Correct: https://github.com/microsoft/vscode
# Wrong: https://github.com/Microsoft/VSCode

Generation Timeouts

Symptoms:

Generation hangs indefinitely
Timeout errors after long wait
Partial generation results

Diagnosis:

# Check generation progress
curl -s http://localhost:8001/wiki/projects | jq '.[].status'

# Monitor resource usage during generation
top -p $(pgrep -f "python.*api")
free -h
df -h

# Check for specific timeout errors
grep -i timeout ./api/logs/application.log

Solutions:

Increase Timeouts
Optimize Large Repositories
Resource Monitoring

# In API configuration
GENERATION_TIMEOUT = 1800  # 30 minutes
REQUEST_TIMEOUT = 300      # 5 minutes per API call
CLONE_TIMEOUT = 600        # 10 minutes for repository clone

Quality Issues

Poor Documentation Quality

Symptoms:

Generic, unhelpful descriptions
Missing technical details
Incorrect architecture analysis
Nonsensical content

Diagnosis:

# Check repository quality indicators
cd /path/to/cloned/repo
find . -name "README*" -o -name "*.md" | head -10
grep -r "class\|function\|def\|interface" . | wc -l
ls -la package.json setup.py requirements.txt 2>/dev/null

Solutions:

Improve Input Quality
Use Better Models
Enable Deep Research

# Enhance repository before generation
# 1. Update README.md with current info
# 2. Add code comments to complex functions
# 3. Include configuration examples
# 4. Add API documentation files

# Example improvements:
echo "# Updated Project Description" >> README.md
echo "## Architecture Overview" >> README.md
echo "## API Endpoints" >> README.md

Incomplete Generation

Symptoms:

Missing pages or sections
Truncated content
Empty or broken diagrams

Diagnosis:

# Check generation logs for truncation
grep -i "truncated\|incomplete\|error" ./api/logs/application.log

# Verify file processing
curl -s http://localhost:8001/wiki/projects | \
  jq '.[] | select(.repo_url | contains("your-repo")) | .metadata'

# Check token limits
grep -i "token.*limit" ./api/logs/application.log

Solutions:

Token Limit Management
Iterative Generation
Manual Completion

# Adjust token limits
MAX_INPUT_TOKENS = 100000   # Increase context
MAX_OUTPUT_TOKENS = 8192    # Increase response length
CHUNK_OVERLAP = 0.2         # More overlap between chunks

Performance Issues

Slow Generation Speed

Optimization Strategies

Diagnosis:

# Profile generation time
time curl -X POST "http://localhost:8001/wiki/generate" \
  -d '{"repo_url": "https://github.com/small/repo"}'

# Check bottlenecks
grep -E "took|duration|time" ./api/logs/application.log | tail -10

# Monitor resource usage
iostat -x 1 5  # Disk I/O
top -p $(pgrep python)  # CPU/Memory

Solutions:

Model Selection
Processing Optimization
Infrastructure

{
  "speed_optimization": {
    "fast_model": "gemini-2.0-flash",     // Fastest
    "balanced": "gpt-4o-mini",            // Fast + good quality  
    "quality": "gpt-4o"                   // Slow but best quality
  }
}

Memory Issues

Symptoms:

Out of memory errors
System becoming unresponsive
Process killed by OS

Solutions:

# Monitor memory usage
watch -n 2 'free -h && echo "---" && ps aux --sort=-%mem | head -10'

# Set memory limits
ulimit -m 8000000  # 8GB limit
export MALLOC_ARENA_MAX=2

# Configure Python garbage collection
export PYTHONOPTIMIZE=1
export PYTHONUNBUFFERED=1

# Use memory-efficient models
# Prefer: gemini-flash, gpt-4o-mini
# Avoid: large local models if RAM limited

Docker Issues

Container Problems

Docker Compose Issues

Symptoms:

Containers fail to start
Service communication failures
Volume mount issues

Diagnosis:

# Check container status
docker-compose ps

# View logs
docker-compose logs api
docker-compose logs frontend

# Check network connectivity
docker-compose exec api curl http://localhost:8001/health
docker-compose exec frontend curl http://api:8001/health

Solutions:

Service Communication
Volume Issues
Resource Limits

# In docker-compose.yml
services:
  api:
    environment:
      - PORT=8001
  frontend:
    environment:
      - SERVER_BASE_URL=http://api:8001  # Use service name

Image Build Failures

Solutions:

# Clear build cache
docker system prune -f
docker-compose build --no-cache

# Check Dockerfile syntax
docker build --dry-run -f Dockerfile .

# Build with verbose output
docker-compose build --progress=plain

# Use multi-stage build for debugging
docker build --target=development -t deepwiki-debug .
docker run -it deepwiki-debug /bin/bash

Advanced Troubleshooting

Debug Mode

Enable Debug Logging

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

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

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:

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

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

GitHub Issues

Report bugs and request features

Discord Community

Get community support and discuss issues

Documentation

Review comprehensive setup and usage guides

FAQ

Check frequently asked questions

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

Performance Guide

Optimize DeepWiki for better performance

Security Guide

Secure your DeepWiki deployment

Production Setup

Deploy DeepWiki in production environments

Monitoring

Set up monitoring and alerting

Get Started

Configuration

Advanced

Support

Quick Diagnostic Checklist

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

Performance Profiling

Getting Help

Collect Debug Information

Community Resources

GitHub Issues

Discord Community

Documentation

FAQ

Next Steps

Performance Guide

Security Guide

Production Setup

Monitoring

Get Started

Configuration

Advanced

Support

​Quick Diagnostic Checklist

​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

​Performance Profiling

​Getting Help

​Collect Debug Information

​Community Resources

GitHub Issues

Discord Community

Documentation

FAQ

​Next Steps

Performance Guide

Security Guide

Production Setup

Monitoring

Quick Diagnostic Checklist

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

Performance Profiling

Getting Help

Collect Debug Information

Community Resources

Next Steps