> ## Documentation Index
> Fetch the complete documentation index at: https://asyncfunc.mintlify.app/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:

<Steps>
  <Step title="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)"
    ```

    <Check>
      All services running and responding correctly
    </Check>
  </Step>

  <Step title="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"
    ```

    <Info>
      Look for error patterns, failed requests, or configuration warnings
    </Info>
  </Step>

  <Step title="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"
      }'
    ```

    <Check>
      Basic functionality working as expected
    </Check>
  </Step>
</Steps>

## Installation Issues

### Python Installation Problems

<AccordionGroup>
  <Accordion title="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:**

    <Tabs>
      <Tab title="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>

      <Tab title="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>

      <Tab title="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
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Dependency Installation Failures">
    **Symptoms:**

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

    **Solutions:**

    <Tabs>
      <Tab title="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>

      <Tab title="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>

      <Tab title="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
        ```
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

### Node.js and Frontend Issues

<AccordionGroup>
  <Accordion title="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:**

    <Tabs>
      <Tab title="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>

      <Tab title="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>

      <Tab title="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"
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="npm Permission Errors">
    **Symptoms:**

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

    **Solutions:**

    <Tabs>
      <Tab title="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>

      <Tab title="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
        ```
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

## API and Service Issues

### API Connection Problems

<AccordionGroup>
  <Accordion title="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:**

    <Tabs>
      <Tab title="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>

      <Tab title="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>

      <Tab title="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
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="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:**

    <Tabs>
      <Tab title="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>

      <Tab title="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>

      <Tab title="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
        ```
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

### AI Provider Issues

<AccordionGroup>
  <Accordion title="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:**

    <Tabs>
      <Tab title="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>

      <Tab title="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>

      <Tab title="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
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="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:**

    <Tabs>
      <Tab title="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>

      <Tab title="Use Multiple Providers">
        ```javascript theme={null}
        {
          "provider_fallback": {
            "primary": "google",
            "fallback_on_rate_limit": "openai",
            "fallback_delay": 60
          }
        }
        ```
      </Tab>

      <Tab title="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
        ```
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

## Wiki Generation Issues

### Generation Failures

<AccordionGroup>
  <Accordion title="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:**

    <Tabs>
      <Tab title="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>

      <Tab title="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>

      <Tab title="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
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="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:**

    <Tabs>
      <Tab title="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>

      <Tab title="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>

      <Tab title="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
        ```
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

### Quality Issues

<AccordionGroup>
  <Accordion title="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:**

    <Tabs>
      <Tab title="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>

      <Tab title="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>

      <Tab title="Enable Deep Research">
        ```javascript theme={null}
        {
          "generation_config": {
            "deep_research": true,
            "analysis_depth": "detailed",
            "include_examples": true,
            "cross_reference": true
          }
        }
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="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:**

    <Tabs>
      <Tab title="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>

      <Tab title="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>

      <Tab title="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
          }'
        ```
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

## Performance Issues

### Slow Generation Speed

<AccordionGroup>
  <Accordion title="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:**

    <Tabs>
      <Tab title="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>

      <Tab title="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>

      <Tab title="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
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="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
    ```
  </Accordion>
</AccordionGroup>

## Docker Issues

### Container Problems

<AccordionGroup>
  <Accordion title="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:**

    <Tabs>
      <Tab title="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>

      <Tab title="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>

      <Tab title="Resource Limits">
        ```yaml theme={null}
        # In docker-compose.yml
        services:
          api:
            deploy:
              resources:
                limits:
                  memory: 4G
                  cpus: '2'
                reservations:
                  memory: 2G
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="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
    ```
  </Accordion>
</AccordionGroup>

## Advanced Troubleshooting

### Debug Mode

<Steps>
  <Step title="Enable Debug Logging">
    ```env theme={null}
    LOG_LEVEL=DEBUG
    LOG_FILE_PATH=./api/logs/debug.log
    ```
  </Step>

  <Step title="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
    ```
  </Step>

  <Step title="Frontend Debug Mode">
    ```bash theme={null}
    # Next.js debug mode
    DEBUG=* npm run dev

    # Or with detailed logging
    NODE_OPTIONS='--inspect' npm run dev
    ```
  </Step>
</Steps>

### Performance Profiling

<CodeGroup>
  ```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
  ```
</CodeGroup>

## Getting Help

### Collect Debug Information

Before seeking help, collect this information:

<Steps>
  <Step title="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
    ```
  </Step>

  <Step title="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"
      }'
    ```
  </Step>
</Steps>

### Community Resources

<CardGroup cols={2}>
  <Card title="GitHub Issues" icon="github" href="https://github.com/AsyncFuncAI/deepwiki-open/issues">
    Report bugs and request features
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.com/invite/VQMBGR8u5v">
    Get community support and discuss issues
  </Card>

  <Card title="Documentation" icon="book" href="/getting-started/introduction">
    Review comprehensive setup and usage guides
  </Card>

  <Card title="FAQ" icon="question-circle" href="/reference/faq">
    Check frequently asked questions
  </Card>
</CardGroup>

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

<CardGroup cols={2}>
  <Card title="Performance Guide" icon="gauge" href="/reference/performance">
    Optimize DeepWiki for better performance
  </Card>

  <Card title="Security Guide" icon="shield" href="/reference/security">
    Secure your DeepWiki deployment
  </Card>

  <Card title="Production Setup" icon="cloud" href="/guides/production-setup">
    Deploy DeepWiki in production environments
  </Card>

  <Card title="Monitoring" icon="chart-line" href="/reference/monitoring">
    Set up monitoring and alerting
  </Card>
</CardGroup>