docs/TROUBLESHOOTING.md

Troubleshooting Guide

This guide covers common issues and their solutions when using WanGP.

Installation Issues

PyTorch Installation Problems

CUDA Version Mismatch

Problem: PyTorch can't detect GPU or CUDA errors Solution:

# Check your CUDA version
nvidia-smi

# Install matching PyTorch version
# For CUDA 12.4 (RTX 10XX-40XX)
pip install torch==2.6.0 torchvision torchaudio --index-url https://download.pytorch.org/whl/test/cu124

# For CUDA 12.8 (RTX 50XX)
pip install torch==2.7.0 torchvision torchaudio --index-url https://download.pytorch.org/whl/test/cu128

Python Version Issues

Problem: Package compatibility errors Solution: Ensure you're using Python 3.10.9

python --version  # Should show 3.10.9
conda create -n wan2gp python=3.10.9

Dependency Installation Failures

Triton Installation (Windows)

Problem: pip install triton-windows fails Solution:

1. Update pip: pip install --upgrade pip
2. Try pre-compiled wheel
3. Fallback to SDPA attention: python wgp.py --attention sdpa

SageAttention Compilation Issues

Problem: SageAttention installation fails Solution:

1. Install Visual Studio Build Tools (Windows)
2. Use pre-compiled wheels when available
3. Fallback to basic attention modes

Memory Issues

CUDA Out of Memory

During Model Loading

Problem: "CUDA out of memory" when loading model Solutions:

# Use smaller model
python wgp.py --t2v-1-3B

# Enable quantization (usually default)
python wgp.py --quantize-transformer True

# Use memory-efficient profile
python wgp.py --profile 4

# Reduce preloaded model size
python wgp.py --preload 0

During Video Generation

Problem: Memory error during generation Solutions:

1. Reduce frame count (shorter videos)
2. Lower resolution in advanced settings
3. Use lower batch size
4. Clear GPU cache between generations

System RAM Issues

High RAM Usage

Problem: System runs out of RAM Solutions:

# Limit reserved memory
python wgp.py --perc-reserved-mem-max 0.3

# Use minimal RAM profile
python wgp.py --profile 5

# Enable swap file (OS level)

Performance Issues

Slow Generation Speed

General Optimization

# Enable compilation (requires Triton)
python wgp.py --compile

# Use faster attention
python wgp.py --attention sage2

# Enable TeaCache
python wgp.py --teacache 2.0

# Use high-performance profile
python wgp.py --profile 3

GPU-Specific Optimizations

RTX 10XX/20XX Series:

python wgp.py --attention sdpa --profile 4 --teacache 1.5

RTX 30XX/40XX Series:

python wgp.py --compile --attention sage --profile 3 --teacache 2.0

RTX 50XX Series:

python wgp.py --attention sage --profile 4 --fp16

Attention Mechanism Issues

Sage Attention Not Working

Problem: Sage attention fails to compile or work Diagnostic Steps:

1. Check Triton installation:

   import triton
   print(triton.__version__)
   

2. Clear Triton cache:

   # Windows
   rmdir /s %USERPROFILE%\.triton
   # Linux
   rm -rf ~/.triton
   

3. Fallback solution:

   python wgp.py --attention sdpa
   

Flash Attention Issues

Problem: Flash attention compilation fails Solution:

• Windows: Often requires manual CUDA kernel compilation
• Linux: Usually works with pip install flash-attn
• Fallback: Use Sage or SDPA attention

Model-Specific Issues

Lora Problems

Loras Not Loading

Problem: Loras don't appear in the interface Solutions:

1. Check file format (should be .safetensors, .pt, or .pth)
2. Verify correct directory:

   loras/          # For t2v models
   loras_i2v/      # For i2v models
   loras_hunyuan/  # For Hunyuan models
   

3. Click "Refresh" button in interface
4. Use --check-loras to filter incompatible files

Lora Compatibility Issues

Problem: Lora causes errors or poor results Solutions:

1. Check model size compatibility (1.3B vs 14B)
2. Verify lora was trained for your model type
3. Try different multiplier values
4. Use --check-loras flag to auto-filter

VACE-Specific Issues

Poor VACE Results

Problem: VACE generates poor quality or unexpected results Solutions:

1. Enable Skip Layer Guidance
2. Use detailed prompts describing all elements
3. Ensure proper mask creation with Matanyone
4. Check reference image quality
5. Use at least 15 steps, preferably 30+

Matanyone Tool Issues

Problem: Mask creation difficulties Solutions:

1. Use negative point prompts to refine selection
2. Create multiple sub-masks and combine them
3. Try different background removal options
4. Ensure sufficient contrast in source video

Network and Server Issues

Gradio Interface Problems

Port Already in Use

Problem: "Port 7860 is already in use" Solution:

# Use different port
python wgp.py --server-port 7861

# Or kill existing process
# Windows
netstat -ano | findstr :7860
taskkill /PID <PID> /F

# Linux
lsof -i :7860
kill <PID>

Interface Not Loading

Problem: Browser shows "connection refused" Solutions:

1. Check if server started successfully
2. Try http://127.0.0.1:7860 instead of localhost:7860
3. Disable firewall temporarily
4. Use --listen flag for network access

Remote Access Issues

Sharing Not Working

Problem: --share flag doesn't create public URL Solutions:

1. Check internet connection
2. Try different network
3. Use --listen with port forwarding
4. Check firewall settings

Quality Issues

Poor Video Quality

General Quality Improvements

1. Increase number of steps (25-30+)
2. Use larger models (14B instead of 1.3B)
3. Enable Skip Layer Guidance
4. Improve prompt descriptions
5. Use higher resolution settings

Specific Quality Issues

Blurry Videos:

• Increase steps
• Check source image quality (i2v)
• Reduce TeaCache multiplier
• Use higher guidance scale

Inconsistent Motion:

• Use longer overlap in sliding windows
• Reduce window size
• Improve prompt consistency
• Check control video quality (VACE)

Color Issues:

• Check model compatibility
• Adjust guidance scale
• Verify input image color space
• Try different VAE settings

Advanced Debugging

Enable Verbose Output

# Maximum verbosity
python wgp.py --verbose 2

# Check lora compatibility
python wgp.py --check-loras --verbose 2

Memory Debugging

# Monitor GPU memory
nvidia-smi -l 1

# Reduce memory usage
python wgp.py --profile 4 --perc-reserved-mem-max 0.2

Performance Profiling

# Test different configurations
python wgp.py --attention sdpa --profile 4  # Baseline
python wgp.py --attention sage --profile 3  # Performance
python wgp.py --compile --teacache 2.0      # Maximum speed

Getting Help

Before Asking for Help

1. Check this troubleshooting guide
2. Read the relevant documentation:
   • Installation Guide
   • Getting Started
   • Command Line Reference
3. Try basic fallback configuration:

   python wgp.py --attention sdpa --profile 4
   

Community Support

• Discord Server: https://discord.gg/g7efUW9jGV
• Provide relevant information:
  • GPU model and VRAM amount
  • Python and PyTorch versions
  • Complete error messages
  • Command used to launch WanGP
  • Operating system

Reporting Bugs

When reporting issues:

1. Include system specifications
2. Provide complete error logs
3. List the exact steps to reproduce
4. Mention any modifications to default settings
5. Include command line arguments used

Emergency Fallback

If nothing works, try this minimal configuration:

# Absolute minimum setup
python wgp.py --t2v-1-3B --attention sdpa --profile 4 --teacache 0 --fp16

# If that fails, check basic PyTorch installation
python -c "import torch; print(torch.cuda.is_available())"