> ## Documentation Index
> Fetch the complete documentation index at: https://asyncfunc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Guide

> Comprehensive troubleshooting guide for common DeepWiki-Open issues, errors, and performance problems

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

```bash theme={null}
# 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)"
```

> [!TIP]
>
> All services running and responding correctly

**2. Review Recent Logs**

```bash theme={null}
# 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"
```

> [!NOTE]
>
> Look for error patterns, failed requests, or configuration warnings

**3. Test Basic Functionality**

```bash theme={null}
# 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"
  }'
```

> [!TIP]
>
> Basic functionality working as expected

## Installation Issues

### Python Installation Problems

> [accordion] Python Version Conflicts
>
> **Symptoms:**
>
> * `python: command not found`
> * `ImportError: No module named 'fastapi'`
> * Version mismatch errors
>
> **Diagnosis:**
>
> ```bash theme={null}
> # Check Python version and location
> python --version
> python3 --version
> which python
> which python3
>
> # Check virtual environment
> echo $VIRTUAL_ENV
> pip list | head -10
> ```
>
> **Solutions:**
>
> > [tab] Use Python 3 Explicitly
> >
> > ```bash theme={null}
> > # 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
> > ```
>
> > [tab] Fix Virtual Environment
> >
> > ```bash theme={null}
> > # 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
> > ```
>
> > [tab] Use pyenv (Recommended)
> >
> > ```bash theme={null}
> > # 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
> > ```

> [accordion] Dependency Installation Failures
>
> **Symptoms:**
>
> * `error: Microsoft Visual C++ 14.0 is required` (Windows)
> * `Failed building wheel for numpy`
> * Permission denied errors
>
> **Solutions:**
>
> > [tab] Windows
> >
> > ```powershell theme={null}
> > # 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
> > ```
>
> > [tab] macOS
> >
> > ```bash theme={null}
> > # 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
> > ```
>
> > [tab] Linux
> >
> > ```bash theme={null}
> > # 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

> [accordion] Node.js Version Issues
>
> **Symptoms:**
>
> * `npm ERR! unsupported engine`
> * React/Next.js compatibility errors
> * Build failures
>
> **Diagnosis:**
>
> ```bash theme={null}
> # 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:**
>
> > [tab] Update Node.js
> >
> > ```bash theme={null}
> > # 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
> > ```
>
> > [tab] Use Yarn Instead
> >
> > ```bash theme={null}
> > # Install Yarn
> > npm install -g yarn
> >
> > # Clear npm cache and use Yarn
> > rm -rf node_modules package-lock.json
> > yarn install
> > yarn dev
> > ```
>
> > [tab] Docker Alternative
> >
> > ```bash theme={null}
> > # 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"
> > ```

> [accordion] npm Permission Errors
>
> **Symptoms:**
>
> * `npm ERR! EACCES: permission denied`
> * `cannot run in wd` errors
> * Global package installation failures
>
> **Solutions:**
>
> > [tab] Fix npm Permissions
> >
> > ```bash theme={null}
> > # 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
> > ```
>
> > [tab] Use Node Version Manager
> >
> > ```bash theme={null}
> > # 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

> [accordion] Backend API Not Starting
>
> **Symptoms:**
>
> * `Connection refused` errors
> * No response from `localhost:8001`
> * FastAPI startup failures
>
> **Diagnosis:**
>
> ```bash theme={null}
> # 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:**
>
> > [tab] Port Conflicts
> >
> > ```bash theme={null}
> > # 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
> > ```
>
> > [tab] Missing Dependencies
> >
> > ```bash theme={null}
> > # 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
> > ```
>
> > [tab] Configuration Issues
> >
> > ```bash theme={null}
> > # 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
> > ```

> [accordion] Frontend Connection Issues
>
> **Symptoms:**
>
> * Frontend loads but can't connect to API
> * CORS errors in browser console
> * Network request failures
>
> **Diagnosis:**
>
> ```bash theme={null}
> # 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:**
>
> > [tab] CORS Configuration
> >
> > ```python theme={null}
> > # 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=["*"],
> > )
> > ```
>
> > [tab] API URL Configuration
> >
> > ```javascript theme={null}
> > // 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
> > ```
>
> > [tab] Network Debugging
> >
> > ```bash theme={null}
> > # 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

> [accordion] API Key Problems
>
> **Symptoms:**
>
> * "Invalid API key" errors
> * Authentication failures
> * Provider-specific error messages
>
> **Diagnosis:**
>
> ```bash theme={null}
> # 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:**
>
> > [tab] Google API Key
> >
> > ```bash theme={null}
> > # 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
> > ```
>
> > [tab] OpenAI API Key
> >
> > ```bash theme={null}
> > # 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
> > ```
>
> > [tab] Environment Loading
> >
> > ```bash theme={null}
> > # 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
> > ```

> [accordion] Rate Limiting Issues
>
> **Symptoms:**
>
> * "Too many requests" errors
> * Slow or hanging generation
> * HTTP 429 responses
>
> **Diagnosis:**
>
> ```bash theme={null}
> # 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:**
>
> > [tab] Adjust Rate Limits
> >
> > ```python theme={null}
> > # 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
> >     }
> > }
> > ```
>
> > [tab] Use Multiple Providers
> >
> > ```javascript theme={null}
> > {
> >   "provider_fallback": {
> >     "primary": "google",
> >     "fallback_on_rate_limit": "openai",
> >     "fallback_delay": 60
> >   }
> > }
> > ```
>
> > [tab] Optimize Requests
> >
> > ```python theme={null}
> > # 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

> [accordion] Repository Access Issues
>
> **Symptoms:**
>
> * "Repository not found" errors
> * Private repository access denied
> * Authentication failures for repositories
>
> **Diagnosis:**
>
> ```bash theme={null}
> # 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:**
>
> > [tab] Public Repository Issues
> >
> > ```bash theme={null}
> > # 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
> > ```
>
> > [tab] Private Repository Setup
> >
> > ```bash theme={null}
> > # 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"
> >   }'
> > ```
>
> > [tab] GitLab/BitBucket
> >
> > ```bash theme={null}
> > # 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
> > ```

> [accordion] Generation Timeouts
>
> **Symptoms:**
>
> * Generation hangs indefinitely
> * Timeout errors after long wait
> * Partial generation results
>
> **Diagnosis:**
>
> ```bash theme={null}
> # 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:**
>
> > [tab] Increase Timeouts
> >
> > ```python theme={null}
> > # In API configuration
> > GENERATION_TIMEOUT = 1800  # 30 minutes
> > REQUEST_TIMEOUT = 300      # 5 minutes per API call
> > CLONE_TIMEOUT = 600        # 10 minutes for repository clone
> > ```
>
> > [tab] Optimize Large Repositories
> >
> > ```javascript theme={null}
> > {
> >   "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
> >   }
> > }
> > ```
>
> > [tab] Resource Monitoring
> >
> > ```bash theme={null}
> > # 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

> [accordion] Poor Documentation Quality
>
> **Symptoms:**
>
> * Generic, unhelpful descriptions
> * Missing technical details
> * Incorrect architecture analysis
> * Nonsensical content
>
> **Diagnosis:**
>
> ```bash theme={null}
> # 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:**
>
> > [tab] Improve Input Quality
> >
> > ```bash theme={null}
> > # 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
> > ```
>
> > [tab] Use Better Models
> >
> > ```javascript theme={null}
> > {
> >   "model_upgrade": {
> >     "from": "gemini-1.5-flash",
> >     "to": "gpt-4o",
> >     "reason": "Need higher quality analysis for complex codebase"
> >   }
> > }
> > ```
>
> > [tab] Enable Deep Research
> >
> > ```javascript theme={null}
> > {
> >   "generation_config": {
> >     "deep_research": true,
> >     "analysis_depth": "detailed",
> >     "include_examples": true,
> >     "cross_reference": true
> >   }
> > }
> > ```

> [accordion] Incomplete Generation
>
> **Symptoms:**
>
> * Missing pages or sections
> * Truncated content
> * Empty or broken diagrams
>
> **Diagnosis:**
>
> ```bash theme={null}
> # 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:**
>
> > [tab] Token Limit Management
> >
> > ```python theme={null}
> > # Adjust token limits
> > MAX_INPUT_TOKENS = 100000   # Increase context
> > MAX_OUTPUT_TOKENS = 8192    # Increase response length
> > CHUNK_OVERLAP = 0.2         # More overlap between chunks
> > ```
>
> > [tab] Iterative Generation
> >
> > ```bash theme={null}
> > # 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}'
> > ```
>
> > [tab] Manual Completion
> >
> > ```bash theme={null}
> > # 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

> [accordion] Optimization Strategies
>
> **Diagnosis:**
>
> ```bash theme={null}
> # 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:**
>
> > [tab] Model Selection
> >
> > ```javascript theme={null}
> > {
> >   "speed_optimization": {
> >     "fast_model": "gemini-2.0-flash",     // Fastest
> >     "balanced": "gpt-4o-mini",            // Fast + good quality  
> >     "quality": "gpt-4o"                   // Slow but best quality
> >   }
> > }
> > ```
>
> > [tab] Processing Optimization
> >
> > ```python theme={null}
> > # 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
> > ```
>
> > [tab] Infrastructure
> >
> > ```bash theme={null}
> > # 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
> > ```

> [accordion] Memory Issues
>
> **Symptoms:**
>
> * Out of memory errors
> * System becoming unresponsive
> * Process killed by OS
>
> **Solutions:**
>
> ```bash theme={null}
> # 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

> [accordion] Docker Compose Issues
>
> **Symptoms:**
>
> * Containers fail to start
> * Service communication failures
> * Volume mount issues
>
> **Diagnosis:**
>
> ```bash theme={null}
> # 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:**
>
> > [tab] Service Communication
> >
> > ```yaml theme={null}
> > # In docker-compose.yml
> > services:
> >   api:
> >     environment:
> >       - PORT=8001
> >   frontend:
> >     environment:
> >       - SERVER_BASE_URL=http://api:8001  # Use service name
> > ```
>
> > [tab] Volume Issues
> >
> > ```bash theme={null}
> > # 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
> > ```
>
> > [tab] Resource Limits
> >
> > ```yaml theme={null}
> > # In docker-compose.yml
> > services:
> >   api:
> >     deploy:
> >       resources:
> >         limits:
> >           memory: 4G
> >           cpus: '2'
> >         reservations:
> >           memory: 2G
> > ```

> [accordion] Image Build Failures
>
> **Solutions:**
>
> ```bash theme={null}
> # 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

**1. Enable Debug Logging**

```env theme={null}
LOG_LEVEL=DEBUG
LOG_FILE_PATH=./api/logs/debug.log
```

**2. Verbose API Output**

```bash theme={null}
# 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**

```bash theme={null}
# Next.js debug mode
DEBUG=* npm run dev

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

### Performance Profiling

```python Python Profiling theme={null}
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)
```

```bash System Monitoring theme={null}
# Continuous monitoring script
#!/bin/bash
while true; do
  echo "=== $(date) ==="
  echo "Memory:"
  free -h
  echo "CPU:"
  top -bn1 | grep "Cpu(s)" | awk '{print $2}' | cut -d'%' -f1
  echo "Disk I/O:"
  iostat -x 1 1 | grep -E "Device|sda"
  echo "Network:"
  ss -tuln | grep -E ":8001|:3000"
  echo "---"
  sleep 30
done
```

## Getting Help

### Collect Debug Information

Before seeking help, collect this information:

**1. System Information**

```bash theme={null}
# 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:

```bash theme={null}
# 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

> [card] [GitHub Issues](https://github.com/AsyncFuncAI/deepwiki-open/issues)
>
> Report bugs and request features

> [card] [Discord Community](https://discord.com/invite/VQMBGR8u5v)
>
> Get community support and discuss issues

> [card] [Documentation](https://asyncfunc.mintlify.site/getting-started/introduction.md)
>
> Review comprehensive setup and usage guides

> [card] [FAQ](https://asyncfunc.mintlify.site/reference/faq.md)
>
> 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

> [card] [Performance Guide](https://asyncfunc.mintlify.site/reference/performance.md)
>
> Optimize DeepWiki for better performance

> [card] [Security Guide](https://asyncfunc.mintlify.site/reference/security.md)
>
> Secure your DeepWiki deployment

> [card] [Production Setup](https://asyncfunc.mintlify.site/guides/production-setup.md)
>
> Deploy DeepWiki in production environments

> [card] [Monitoring](https://asyncfunc.mintlify.site/reference/monitoring)
>
> Set up monitoring and alerting


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.