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

# Remove existing virtual environment
rm -rf venv

# Create new virtual environment with explicit Python version
python3.10 -m venv venv
# Or
virtualenv -p python3.10 venv

# Activate and install
source venv/bin/activate
pip install --upgrade pip
pip install -r api/requirements.txt

# Install pyenv (macOS)
brew install pyenv

# Install specific Python version
pyenv install 3.10.9
pyenv local 3.10.9

# Create virtual environment
python -m venv venv
source venv/bin/activate
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

# Install Xcode command line tools
xcode-select --install

# Install system dependencies via Homebrew
brew install python@3.10

# Use system Python with virtual environment
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install -r api/requirements.txt

# Install system dependencies (Ubuntu/Debian)
sudo apt update
sudo apt install python3-dev python3-pip python3-venv
sudo apt install build-essential libssl-dev libffi-dev

# Create virtual environment
python3 -m venv venv
source venv/bin/activate
pip install --upgrade 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

# Install Yarn
npm install -g yarn

# Clear npm cache and use Yarn
rm -rf node_modules package-lock.json
yarn install
yarn dev

# Use Node.js in Docker to avoid version conflicts
docker run -it --rm \
  -v $(pwd):/app \
  -w /app \
  -p 3000:3000 \
  node:18-alpine \
  sh -c "npm install && npm run dev"

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

# Install nvm (handles permissions automatically)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc

# Install and use Node.js
nvm install 18
nvm use 18
nvm alias default 18

# Now npm will work without sudo
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

# Ensure virtual environment is activated
source venv/bin/activate

# Check if all dependencies are installed
pip check

# Reinstall requirements
pip install --force-reinstall -r api/requirements.txt

# Start with verbose logging
LOG_LEVEL=DEBUG python -m api.main

# Check environment variables
python -c "
import os
from dotenv import load_dotenv
load_dotenv()
print('GOOGLE_API_KEY:', 'SET' if os.getenv('GOOGLE_API_KEY') else 'NOT SET')
print('OPENAI_API_KEY:', 'SET' if os.getenv('OPENAI_API_KEY') else 'NOT SET')
print('PORT:', os.getenv('PORT', '8001'))
"

# Verify .env file exists and is readable
ls -la .env
cat .env | grep -v "API_KEY"  # Don't show actual keys

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=["*"],
)

// In next.config.js or environment
const nextConfig = {
  env: {
    API_BASE_URL: process.env.SERVER_BASE_URL || 'http://localhost:8001'
  }
}

// Or in .env.local
SERVER_BASE_URL=http://localhost:8001

# Test network connectivity
curl -v http://localhost:8001/health

# Check firewall settings
sudo ufw status  # Linux
# Or check Windows Firewall/macOS Firewall

# Test from different terminal/shell
telnet localhost 8001

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

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

# Common issues:
# 1. Account needs billing setup
# 2. Key expired or revoked
# 3. Rate limits exceeded

# Fix: Check OpenAI dashboard
# Add payment method
# Generate new key if needed

# Ensure .env is being loaded
python -c "
from dotenv import load_dotenv
import os
load_dotenv()
print('.env file loaded')
print('Keys found:', [k for k in os.environ if 'API_KEY' in k])
"

# Check file permissions
ls -la .env

# Verify no BOM or special characters
file .env
hexdump -C .env | head -5

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
    }
}

{
  "provider_fallback": {
    "primary": "google",
    "fallback_on_rate_limit": "openai",
    "fallback_delay": 60
  }
}

# Reduce token usage
MAX_INPUT_TOKENS = 50000  # Reduce from default
BATCH_SIZE = 5            # Process fewer files at once
RETRY_ATTEMPTS = 3        # Reduce retry attempts

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

# GitHub personal access token
# 1. Go to Settings → Developer settings → Personal access tokens
# 2. Generate token with 'repo' scope
# 3. Use in request:

curl -X POST "http://localhost:8001/wiki/generate" \
  -d '{
    "repo_url": "https://github.com/company/private-repo",
    "access_token": "ghp_xxxxxxxxxxxxxxxxxxxx",
    "model_provider": "google"
  }'

# GitLab personal access token
# Scope: read_repository

# BitBucket app password  
# Permission: Repositories: Read

# Test access
curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://api.gitlab.com/v4/projects/owner%2Frepo

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

{
  "optimization": {
    "skip_large_files": true,      // Skip files > 1MB
    "ignore_patterns": [
      "*.min.js",
      "node_modules/**",
      "vendor/**",
      "build/**",
      "dist/**"
    ],
    "max_files_per_batch": 10,     // Process fewer files
    "enable_caching": true         // Cache intermediate results
  }
}

# Monitor during generation
watch -n 5 'ps aux | grep python | grep -v grep'
watch -n 5 'free -h && df -h'

# Set system limits
ulimit -v 8388608  # Limit to 8GB RAM
ulimit -t 1800     # 30 minute CPU limit

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

{
  "model_upgrade": {
    "from": "gemini-1.5-flash",
    "to": "gpt-4o",
    "reason": "Need higher quality analysis for complex codebase"
  }
}

{
  "generation_config": {
    "deep_research": true,
    "analysis_depth": "detailed",
    "include_examples": true,
    "cross_reference": true
  }
}

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

# Generate in stages
# 1. Basic structure first
curl -X POST "http://localhost:8001/wiki/generate" \
  -d '{"repo_url": "...", "focus": "structure"}'

# 2. Detailed content second  
curl -X POST "http://localhost:8001/wiki/generate" \
  -d '{"repo_url": "...", "focus": "content", "force_regenerate": false}'

# Use Ask feature to complete missing sections
curl -X POST "http://localhost:8001/chat/stream" \
  -d '{
    "message": "Generate detailed documentation for the authentication module",
    "repo_url": "https://github.com/user/repo",
    "deep_research": true
  }'

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
  }
}

# Optimize file processing
CONCURRENT_REQUESTS = 3    # Parallel API calls
BATCH_SIZE = 5            # Files per batch
CACHE_EMBEDDINGS = True   # Reuse embeddings
SKIP_BINARY_FILES = True  # Skip non-text files

# Use faster storage
sudo mount -t tmpfs -o size=2G tmpfs /tmp/deepwiki-cache

# Increase worker processes  
export WORKERS=4
gunicorn -w 4 -k uvicorn.workers.UvicornWorker api.api:app

# Use faster DNS
echo "nameserver 1.1.1.1" >> /etc/resolv.conf

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

# Check volume permissions
docker-compose exec api ls -la /app
docker-compose exec api ls -la /app/.env

# Fix permissions
sudo chown -R 1000:1000 ./api/logs
chmod 644 .env

# In docker-compose.yml
services:
  api:
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: '2'
        reservations:
          memory: 2G

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

Documentation Index

​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