diff --git a/docs.json b/docs.json
index cddc25ae5..187172737 100644
--- a/docs.json
+++ b/docs.json
@@ -209,6 +209,15 @@
}
]
},
+ {
+ "group": "Troubleshooting",
+ "icon": "bug",
+ "pages": [
+ "troubleshooting/overview",
+ "troubleshooting/model-issues",
+ "troubleshooting/custom-node-issues"
+ ]
+ },
{
"group": "Community",
"pages": ["community/contributing"]
@@ -660,6 +669,15 @@
}
]
},
+ {
+ "group": "故障排除",
+ "icon": "bug",
+ "pages": [
+ "zh-CN/troubleshooting/overview",
+ "zh-CN/troubleshooting/model-issues",
+ "zh-CN/troubleshooting/custom-node-issues"
+ ]
+ },
{
"group": "社区",
"pages": ["community/contributing"]
@@ -1048,6 +1066,10 @@
{
"source": "tutorials/advanced/hidream-e1",
"destination": "tutorials/image/hidream/hidream-e1"
+ },
+ {
+ "source": "/troubleshooting",
+ "destination": "/troubleshooting/overview"
}
]
}
\ No newline at end of file
diff --git a/images/troubleshooting/Portable-disable-custom-nodes.jpg b/images/troubleshooting/Portable-disable-custom-nodes.jpg
new file mode 100644
index 000000000..e8d34b3c7
Binary files /dev/null and b/images/troubleshooting/Portable-disable-custom-nodes.jpg differ
diff --git a/images/troubleshooting/desktop-diable-custom-node.jpg b/images/troubleshooting/desktop-diable-custom-node.jpg
new file mode 100644
index 000000000..92edc3919
Binary files /dev/null and b/images/troubleshooting/desktop-diable-custom-node.jpg differ
diff --git a/images/troubleshooting/menu-about.jpg b/images/troubleshooting/menu-about.jpg
new file mode 100644
index 000000000..bb150fb00
Binary files /dev/null and b/images/troubleshooting/menu-about.jpg differ
diff --git a/images/troubleshooting/portable-disable-custom-nodes-cml-1.jpg b/images/troubleshooting/portable-disable-custom-nodes-cml-1.jpg
new file mode 100644
index 000000000..c421ff53f
Binary files /dev/null and b/images/troubleshooting/portable-disable-custom-nodes-cml-1.jpg differ
diff --git a/images/troubleshooting/portable-disable-custom-nodes-cml-2.jpg b/images/troubleshooting/portable-disable-custom-nodes-cml-2.jpg
new file mode 100644
index 000000000..e390e670c
Binary files /dev/null and b/images/troubleshooting/portable-disable-custom-nodes-cml-2.jpg differ
diff --git a/images/zh/troubleshooting/desktop-diable-custom-node.jpg b/images/zh/troubleshooting/desktop-diable-custom-node.jpg
new file mode 100644
index 000000000..9c4e81b57
Binary files /dev/null and b/images/zh/troubleshooting/desktop-diable-custom-node.jpg differ
diff --git a/troubleshooting/custom-node-issues.mdx b/troubleshooting/custom-node-issues.mdx
new file mode 100644
index 000000000..4f72c4fb1
--- /dev/null
+++ b/troubleshooting/custom-node-issues.mdx
@@ -0,0 +1,288 @@
+---
+title: "How to Troubleshoot and Solve ComfyUI Issues"
+description: "Troubleshoot and fix problems caused by custom nodes and extensions"
+icon: "puzzle-piece"
+sidebarTitle: "Custom Node Issues"
+---
+
+## Quick Issue Diagnosis
+
+If you're experiencing any of these issues, there is a high likelihood that it is caused by custom nodes:
+- ComfyUI crashes or won't start
+- "Failed to import" errors in console/logs
+- UI completely breaks or shows blank screen
+- "Prompt execution failed" errors not related to memory issues
+- Missing nodes that should be available/installed
+
+## Is It a Custom Node Problem?
+
+Most ComfyUI issues are caused by custom nodes (extensions). Let's check if this is the case.
+
+### Step 1: Test with all custom nodes disabled
+
+Run ComfyUI with all custom nodes disabled:
+
+
+
+Start ComfyUI Desktop with custom nodes disabled from the settings menu
+
+
+
+or run the server manually:
+
+```bash
+cd path/to/your/comfyui
+python main.py --disable-all-custom-nodes
+```
+
+
+```bash
+cd ComfyUI
+python main.py --disable-all-custom-nodes
+```
+
+
+
+
+ Open the folder where the portable version is located, and find the `run_nvidia_gpu.bat` or `run_cpu.bat` file
+
+ 
+ 1. Copy `run_nvidia_gpu.bat` or `run_cpu.bat` file and rename it to `run_nvidia_gpu_disable_custom_nodes.bat`
+ 2. Open the copied file with Notepad
+ 3. Add the `--disable-all-custom-nodes` parameter to the file, or copy the parameters below into a `.txt` file and rename the file to `run_nvidia_gpu_disable_custom_nodes.bat`
+
+ ```bash
+ .\python_embeded\python.exe -s ComfyUI\main.py --disable-all-custom-nodes --windows-standalone-build
+ pause
+ ```
+ 4. Save the file and close it
+ 5. Double-click the file to run it. If everything is normal, you should see ComfyUI start and custom nodes disabled
+
+
+ 
+ 1. Enter the folder where the portable version is located
+ 2. Open the terminal by right-clicking the menu → Open terminal
+
+ 
+
+ 3. Ensure that the folder name is the current directory of the portable version
+ 4. Enter the following command to start ComfyUI through the portable python and disable custom nodes
+ ```
+ .\python_embeded\python.exe -s ComfyUI\main.py --disable-all-custom-nodes
+ ```
+
+
+
+
+
+**Results:**
+- ✅ **Issue disappears**: A custom node is causing the problem → Continue to Step 2
+- ❌ **Issue persists**: Not a custom node issue → [Report the issue](#reporting-issues)
+
+## Step 2: Find the Problematic Custom Node
+
+We'll use **binary search** to quickly find which custom node is causing issues. This is much faster than testing nodes one by one.
+
+### How Binary Search Works
+
+Instead of testing each node individually (which could take hours), we split the nodes in half repeatedly:
+
+```
+8 nodes → Test 4 nodes → Test 2 nodes → Test 1 node ✓
+
+Example with 8 nodes:
+1. Test nodes 1-4: Issue persists ✓ → Problem in remaining nodes 5-8
+2. Test nodes 5-6: Issue gone ✓ → Problem in nodes 7-8
+3. Test node 7: Issue persists ✓ → Node 7 is the problem!
+
+This takes only 3 tests instead of testing all 8 nodes individually.
+```
+
+### Binary Search Process
+
+
+Before starting, **create a backup** of your custom_nodes folder in case something goes wrong.
+
+
+#### Create Temporary Folders
+
+
+
+```bash
+# Create backup and temporary folder
+mkdir "%USERPROFILE%\custom_nodes_backup"
+mkdir "%USERPROFILE%\custom_nodes_temp"
+
+# Backup everything first
+xcopy "custom_nodes\*" "%USERPROFILE%\custom_nodes_backup\" /E /H /Y
+```
+
+
+```bash
+# Create backup and temporary folder
+mkdir ~/custom_nodes_backup
+mkdir ~/custom_nodes_temp
+
+# Backup everything first
+cp -r custom_nodes/* ~/custom_nodes_backup/
+```
+
+
+```bash
+# Create backup and temporary folder
+mkdir /content/custom_nodes_backup
+mkdir /content/custom_nodes_temp
+
+# Backup everything first
+cp -r /content/ComfyUI/custom_nodes/* /content/custom_nodes_backup/
+```
+
+
+
+#### Find the Problematic Node
+
+1. **List your custom nodes:**
+
+
+ ```bash
+ dir custom_nodes
+ ```
+
+
+ ```bash
+ ls custom_nodes/
+ ```
+
+
+ ```bash
+ ls /content/ComfyUI/custom_nodes/
+ ```
+
+
+
+2. **Split nodes in half:**
+
+ Let's say you have 8 custom nodes. Move the first half to temporary storage:
+
+
+
+ ```bash
+ # Move first half (nodes 1-4) to temp
+ move "custom_nodes\node1" "%USERPROFILE%\custom_nodes_temp\"
+ move "custom_nodes\node2" "%USERPROFILE%\custom_nodes_temp\"
+ move "custom_nodes\node3" "%USERPROFILE%\custom_nodes_temp\"
+ move "custom_nodes\node4" "%USERPROFILE%\custom_nodes_temp\"
+ ```
+
+
+ ```bash
+ # Move first half (nodes 1-4) to temp
+ mv custom_nodes/node1 ~/custom_nodes_temp/
+ mv custom_nodes/node2 ~/custom_nodes_temp/
+ mv custom_nodes/node3 ~/custom_nodes_temp/
+ mv custom_nodes/node4 ~/custom_nodes_temp/
+ ```
+
+
+ ```bash
+ # Move first half (nodes 1-4) to temp
+ mv /content/ComfyUI/custom_nodes/node1 /content/custom_nodes_temp/
+ mv /content/ComfyUI/custom_nodes/node2 /content/custom_nodes_temp/
+ mv /content/ComfyUI/custom_nodes/node3 /content/custom_nodes_temp/
+ mv /content/ComfyUI/custom_nodes/node4 /content/custom_nodes_temp/
+ ```
+
+
+
+3. **Test ComfyUI:**
+ ```bash
+ python main.py
+ ```
+
+4. **Interpret results:**
+ - **Issue persists**: Problem is in the remaining nodes (5-8)
+ - **Issue gone**: Problem was in the moved nodes (1-4)
+
+5. **Narrow it down:**
+ - If issue persists: Move half of remaining nodes (e.g., nodes 7-8) to temp
+ - If issue gone: Move half of temp nodes (e.g., nodes 3-4) back to custom_nodes
+
+6. **Repeat until you find the single problematic node**
+
+### Visual Example
+
+Let's walk through a complete example with 8 custom nodes:
+
+```
+📁 custom_nodes/
+├── 🔧 ComfyUI-Manager
+├── 🎨 ComfyUI-Custom-Scripts
+├── 🖼️ ComfyUI-Impact-Pack
+├── 🔄 ComfyUI-Workflow-Component
+├── 📊 ComfyUI-AnimateDiff-Evolved
+├── 🎭 ComfyUI-FaceRestore
+├── ⚡ ComfyUI-Advanced-ControlNet
+└── 🛠️ ComfyUI-Inspire-Pack
+```
+
+**Round 1:** Move first 4 to temp
+- Test → Issue persists ✓
+- Problem is in: ComfyUI-AnimateDiff-Evolved, ComfyUI-FaceRestore, ComfyUI-Advanced-ControlNet, ComfyUI-Inspire-Pack
+
+**Round 2:** Move 2 of the remaining 4 to temp
+- Test → Issue gone ✓
+- Problem is in: ComfyUI-Advanced-ControlNet, ComfyUI-Inspire-Pack
+
+**Round 3:** Move 1 of the remaining 2 to temp
+- Test → Issue persists ✓
+- **Found it!** ComfyUI-Inspire-Pack is the problematic node
+
+## Step 3: Fix the Issue
+
+Once you've identified the problematic custom node:
+
+### Option 1: Update the Node
+1. Check if there's an update available in ComfyUI Manager
+2. Update the node and test again
+
+### Option 2: Replace the Node
+1. Look for alternative custom nodes with similar functionality
+2. Check the [ComfyUI Registry](https://registry.comfy.org) for alternatives
+
+### Option 3: Report the Issue
+Contact the custom node developer:
+1. Find the node's GitHub repository
+2. Create an issue with:
+ - Your ComfyUI version
+ - Error messages/logs
+ - Steps to reproduce
+ - Your operating system
+
+### Option 4: Remove or Disable the Node
+If no fix is available and you don't need the functionality:
+1. Remove the problematic node from `custom_nodes/` or disable it in the ComfyUI Manager interface
+2. Restart ComfyUI
+
+## Reporting Issues
+
+If the issue isn't caused by custom nodes, refer to the general [troubleshooting overview](/troubleshooting/overview) for other common problems.
+
+### For Custom Node-Specific Issues
+Contact the custom node developer:
+- Find the node's GitHub repository
+- Create an issue with your ComfyUI version, error messages, reproduction steps, and OS
+- Check the node's documentation and Issues page for known issues
+
+### For ComfyUI Core Issues
+- **GitHub**: [ComfyUI Issues](https://github.com/comfyanonymous/ComfyUI/issues)
+- **Forum**: [Official ComfyUI Forum](https://forum.comfy.org/)
+
+### For Desktop App Issues
+- **GitHub**: [ComfyUI Desktop Issues](https://github.com/Comfy-Org/desktop/issues)
+
+### For Frontend Issues
+- **GitHub**: [ComfyUI Frontend Issues](https://github.com/Comfy-Org/ComfyUI_frontend/issues)
+
+
+For general installation, model, or performance issues, see our [troubleshooting overview](/troubleshooting/overview) and [model issues](/troubleshooting/model-issues) pages.
+
\ No newline at end of file
diff --git a/troubleshooting/model-issues.mdx b/troubleshooting/model-issues.mdx
new file mode 100644
index 000000000..7a5be5a11
--- /dev/null
+++ b/troubleshooting/model-issues.mdx
@@ -0,0 +1,142 @@
+---
+title: "How to Troubleshoot and Solve ComfyUI Model Issues"
+description: "Troubleshooting model-related problems including architecture mismatches, missing models, and loading errors"
+icon: "cube"
+sidebarTitle: "Model Issues"
+---
+
+## Model Architecture Mismatch
+
+**Symptoms:** Tensor dimension errors during generation, especially during VAE decode stage
+
+**Common error messages:**
+- `Given groups=1, weight of size [64, 4, 3, 3], expected input[1, 16, 128, 128] to have 4 channels, but got 16 channels instead`
+- `Given groups=1, weight of size [4, 4, 1, 1], expected input[1, 16, 144, 112] to have 4 channels, but got 16 channels instead`
+- `Given groups=1, weight of size [320, 4, 3, 3], expected input[2, 16, 192, 128] to have 4 channels, but got 16 channels instead`
+- `The size of tensor a (49) must match the size of tensor b (16) at non-singleton dimension 1`
+- `Tensors must have same number of dimensions: got 2 and 3`
+
+**Root cause:** Using models from different architecture families together
+
+### Solutions
+
+1. **Verify model family compatibility:**
+ - **Flux models** use 16-channel latent space with dual text encoder conditioning (CLIP-L + T5-XXL)
+ - **SD1.5 models** use 4-channel latent space with single CLIP ViT-L/14 text encoder
+ - **SDXL models** use 4-channel latent space with dual text encoders (CLIP ViT-L/14 + OpenCLIP ViT-bigG/14)
+ - **SD3 models** use 16-channel latent space with triple text encoder conditioning (CLIP-L + OpenCLIP bigG + T5-XXL)
+
+2. **Common mismatch scenarios and fixes:**
+
+ **Flux + wrong VAE:**
+ ```
+ Problem: Using taesd or sdxl_vae.safetensors with Flux checkpoint
+ Fix: Use ae.safetensors (Flux VAE) from Hugging Face Flux releases
+ ```
+
+ **Flux + incorrect CLIP configuration:**
+ ```
+ Problem: Using t5xxl_fp8_e4m3fn.safetensors in both CLIP slots of DualClipLoader
+ Fix: Use t5xxl_fp8_e4m3fn.safetensors in one slot and clip_l.safetensors in the other
+ ```
+
+ **ControlNet architecture mismatch:**
+ ```
+ Problem: SD1.5 ControlNet with different architecture checkpoint
+ Fix: Use ControlNet models designed for your checkpoint architecture
+ ```
+
+3. **Quick diagnostics:**
+ ```bash
+ # Check if error occurs at VAE decode stage
+ # Look for "expected input[X, Y, Z] to have N channels, but got M channels"
+ # Y value indicates channel count: 4 = SD models, 16 = Flux models
+ ```
+
+4. **Prevention strategies:**
+ - Keep all workflow models within the same architecture family
+ - Download complete model packages from same source/release (often all in a Hugging Face repo)
+ - When trying new models, start with the template workflows or official ComfyUI workflow examples before customizing
+
+## Missing Models Error
+
+**Example error message:**
+```
+Prompt execution failed
+Prompt outputs failed validation:
+CheckpointLoaderSimple:
+- Value not in list: ckpt_name: 'model-name.safetensors' not in []
+```
+
+### Solutions
+
+1. **Download required models:**
+ - Use ComfyUI Manager to auto-download models
+ - Verify models are in correct subfolders
+
+2. **Check model paths:**
+ - **Checkpoints**: `models/checkpoints/`
+ - **VAE**: `models/vae/`
+ - **LoRA**: `models/loras/`
+ - **ControlNet**: `models/controlnet/`
+ - **Embeddings**: `models/embeddings/`
+
+3. **Share models between UIs or use custom paths:**
+ - See [ComfyUI Model Sharing and Custom Model Directory Configuration](/installation/comfyui_portable_windows#2-comfyui-model-sharing-and-custom-model-directory-configuration) for detailed instructions
+ - Edit `extra_model_paths.yaml` file to add custom model directories
+
+### Model Search Path Configuration
+
+If you have models in custom locations, see the detailed guide for [ComfyUI Model Sharing and Custom Model Directory Configuration](/installation/comfyui_portable_windows#2-comfyui-model-sharing-and-custom-model-directory-configuration) to configure ComfyUI to find them.
+
+## Model Loading Errors
+
+**Error message:** "Error while deserializing header"
+
+### Solutions
+
+1. **Re-download the model** - File may be corrupted during download
+2. **Check available disk space** - Ensure enough space for model loading (models can be 2-15GB+)
+3. **Check file permissions** - Ensure ComfyUI can read the model files
+4. **Test with different model** - Verify if issue is model-specific or system-wide
+
+## Model Performance Issues
+
+### Slow Model Loading
+
+**Symptoms:** Long delays when switching models or starting generation
+
+**Solutions:**
+1. **Use faster storage:**
+ - Move models to SSD if using HDD
+ - Use NVMe SSD for best performance
+
+2. **Adjust caching settings:**
+ ```bash
+ python main.py --cache-classic # Use the old style (aggressive) caching.
+ python main.py --cache-lru 10 # Increase size of LRU cache
+ ```
+
+### Memory Issues with Large Models
+
+**"RuntimeError: CUDA out of memory":**
+
+```bash
+# Progressive memory reduction
+python main.py --lowvram # First try
+python main.py --novram # If lowvram insufficient
+python main.py --cpu # Last resort
+```
+
+**Model-specific memory optimization:**
+```bash
+# Force lower precision
+python main.py --force-fp16
+
+# Reduce attention memory usage
+python main.py --use-pytorch-cross-attention
+```
+
+
+For additional model configuration and setup information, see the [Models documentation](/development/core-concepts/models).
+
\ No newline at end of file
diff --git a/troubleshooting/overview.mdx b/troubleshooting/overview.mdx
new file mode 100644
index 000000000..52561b864
--- /dev/null
+++ b/troubleshooting/overview.mdx
@@ -0,0 +1,472 @@
+---
+title: "How to Troubleshoot and Solve ComfyUI Issues"
+description: "Common ComfyUI issues, solutions, and how to report bugs effectively"
+icon: "lightbulb"
+sidebarTitle: "Overview"
+---
+
+
+ We receive a lot of feedback issues, and we find that most of the issues submitted are related to custom nodes. So please ensure that you have read the [custom node troubleshooting guide](/troubleshooting/custom-node-issues) before submitting an error report to ensure that the issue is not caused by ComfyUI core issues.
+
+
+
+ Check how to troubleshoot issues caused by custom nodes.
+
+
+## Common Issues & Quick Fixes
+
+Before diving into detailed troubleshooting, try these common solutions:
+
+### ComfyUI Won't Start
+
+**Symptoms:** Application crashes on startup, black screen, or fails to load
+
+**Quick fixes:**
+1. **Check system requirements** - Ensure your system meets the [minimum requirements](/installation/system_requirements)
+2. **Update GPU drivers** - Download latest drivers from NVIDIA/AMD/Intel
+
+### Generation Fails or Produces Errors
+
+**Symptoms:** "Prompt execution failed" dialog with "Show report" button, workflow stops executing
+
+**Quick fixes:**
+1. **Click "Show report"** - Read the detailed error message to identify the specific issue
+2. **Check if it's a custom node issue** - [Follow our custom node troubleshooting guide](/troubleshooting/custom-node-issues)
+3. **Verify model files** - See [Models documentation](/development/core-concepts/models) for model setup
+4. **Check VRAM usage** - Close other applications using GPU memory
+
+### Slow Performance
+
+**Symptoms:** Very slow generation times, system freezing, out of memory errors
+
+**Quick fixes:**
+1. **Lower resolution/batch size** - Reduce image size or number of images
+2. **Use memory optimization flags** - See performance optimization section below
+3. **Close unnecessary applications** - Free up RAM and VRAM
+4. **Check CPU/GPU usage** - Use Task Manager to identify bottlenecks
+
+**Performance Optimization Commands:**
+
+For low VRAM systems:
+```bash
+# Low VRAM mode (uses cpu for text encoder)
+python main.py --lowvram
+
+# CPU mode (very slow but works with any hardware, only use as absolute last resort)
+python main.py --cpu
+```
+
+For better performance:
+```bash
+# Disable previews (saves VRAM and processing)
+python main.py --preview-method none
+
+# Use optimized attention mechanisms
+python main.py --use-pytorch-cross-attention
+python main.py --use-flash-attention
+
+# Async weight offloading
+python main.py --async-offload
+```
+
+For memory management:
+```bash
+# Reserve specific VRAM amount for OS (in GB)
+python main.py --reserve-vram 2
+
+# Disable smart memory management
+python main.py --disable-smart-memory
+
+# Use different caching strategies
+python main.py --cache-none # Less RAM usage, but slower
+python main.py --cache-lru 10 # Cache 10 results, faster
+python main.py --cache-classic # Use the old style (aggressive) caching.
+```
+
+## Installation-Specific Issues
+
+### Desktop App Issues
+
+For comprehensive desktop installation troubleshooting, see the [Desktop Installation Guide](/installation/desktop/windows).
+
+
+
+- **Unsupported device**: ComfyUI Desktop Windows only supports NVIDIA GPUs with CUDA. Use [ComfyUI Portable](/installation/comfyui_portable_windows) or [manual installation](/installation/manual_install) for other GPUs
+- **Installation fails**: Run installer as administrator, ensure at least 15GB disk space
+- **Maintenance page**: Check [mirror settings](/installation/desktop/windows#mirror-settings) if downloads fail
+- **Missing models**: Models are not copied during migration, only linked. Verify model paths
+
+
+- **"App is damaged"**: Allow app in Security & Privacy settings
+- **Performance issues**: Grant Full Disk Access in Privacy settings
+- **Crashes**: Check Console app for crash reports
+
+
+- **Missing libraries**: Install dependencies with package manager
+- **LD_LIBRARY_PATH errors**: PyTorch library path issues (see below)
+
+
+
+### Manual Installation Issues
+
+
+The documentation may be slightly out of date. If an issue occurs, please manually verify whether a newer stable version of pytorch or any of the listed libraries exists. Refer to resources like the [pytorch installation matrix](https://pytorch.org/get-started/locally/) or the [ROCm website](https://rocm.docs.amd.com/projects/install-on-linux/en/develop/install/3rd-party/pytorch-install.html#using-a-wheels-package).
+
+
+**Python version conflicts:**
+```bash
+# Check Python version (3.9+ required, 3.12 recommended)
+python --version
+
+# Use virtual environment (recommended)
+python -m venv comfyui_env
+source comfyui_env/bin/activate # Linux/Mac
+comfyui_env\Scripts\activate # Windows
+```
+
+**Package installation failures:**
+```bash
+# Update pip first
+python -m pip install --upgrade pip
+
+# Install dependencies
+pip install -r requirements.txt
+
+# For NVIDIA GPUs (CUDA 12.8)
+pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu128
+
+# For AMD GPUs (Linux only - ROCm 6.3)
+pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.3
+```
+
+### Linux-Specific Issues
+
+**LD_LIBRARY_PATH errors:**
+
+Common symptoms:
+- "libcuda.so.1: cannot open shared object file"
+- "libnccl.so: cannot open shared object file"
+- "ImportError: libnvinfer.so.X: cannot open shared object file"
+
+**Solutions:**
+
+1. **Modern PyTorch installations (most common):**
+```bash
+# For virtual environments with NVIDIA packages
+export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib/python3.12/site-packages/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH
+
+# For conda environments
+export LD_LIBRARY_PATH=$CONDA_PREFIX/lib/python3.12/site-packages/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH
+
+# Or find your Python site-packages automatically
+PYTHON_PATH=$(python -c "import site; print(site.getsitepackages()[0])")
+export LD_LIBRARY_PATH=$PYTHON_PATH/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH
+
+# You may also need other NVIDIA libraries
+export LD_LIBRARY_PATH=$PYTHON_PATH/nvidia/cuda_runtime/lib:$LD_LIBRARY_PATH
+export LD_LIBRARY_PATH=$PYTHON_PATH/nvidia/cublas/lib:$LD_LIBRARY_PATH
+```
+
+2. **Find what libraries you have:**
+```bash
+# Check installed NVIDIA packages
+python -c "import site; import os; nvidia_path=os.path.join(site.getsitepackages()[0], 'nvidia'); print('NVIDIA libs:', [d for d in os.listdir(nvidia_path) if os.path.isdir(os.path.join(nvidia_path, d))] if os.path.exists(nvidia_path) else 'Not found')"
+
+# Find missing libraries that PyTorch needs
+python -c "import torch; print(torch.__file__)"
+ldd $(python -c "import torch; print(torch.__file__.replace('__init__.py', 'lib/libtorch_cuda.so'))")
+```
+
+3. **Set permanently for your environment:**
+```bash
+# For virtual environments, add to activation script
+echo 'export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib/python*/site-packages/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH' >> $VIRTUAL_ENV/bin/activate
+
+# For conda environments
+conda env config vars set LD_LIBRARY_PATH=$CONDA_PREFIX/lib/python*/site-packages/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH
+
+# For global bashrc (adjust Python version as needed)
+echo 'export LD_LIBRARY_PATH=$(python -c "import site; print(site.getsitepackages()[0])")/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH' >> ~/.bashrc
+```
+
+4. **Alternative: Use ldconfig:**
+```bash
+# Check current library cache
+ldconfig -p | grep cuda
+ldconfig -p | grep nccl
+
+# If missing, add library paths (requires root)
+sudo echo "/usr/local/cuda/lib64" > /etc/ld.so.conf.d/cuda.conf
+sudo ldconfig
+```
+
+5. **Debug library loading:**
+```bash
+# Verbose library loading to see what's missing
+LD_DEBUG=libs python main.py 2>&1 | grep "looking for"
+
+# Check PyTorch CUDA availability
+python -c "import torch; print('CUDA available:', torch.cuda.is_available()); print('CUDA version:', torch.version.cuda)"
+```
+
+## Model-Related Issues
+
+For comprehensive model troubleshooting including architecture mismatches, missing models, and loading errors, see the dedicated [Model Issues](/troubleshooting/model-issues) page.
+
+## Network & API Issues
+
+### API Nodes Not Working
+
+**Symptoms:** API calls fail, timeout errors, quota exceeded
+
+**Solutions:**
+1. **Check API key validity** - Verify keys in [user settings](/interface/user)
+2. **Check account credits** - Ensure sufficient [API credits](/interface/credits)
+3. **Verify internet connection** - Test with other online services
+4. **Check service status** - Provider may be experiencing downtime
+
+### Connection Issues
+
+**Symptoms:** "Failed to connect to server", timeout errors
+
+**Solutions:**
+1. **Check firewall settings** - Allow ComfyUI through firewall
+2. **Try different port** - Default is 8188, try 8189 or 8190
+3. **Disable VPN temporarily** - VPN may be blocking connections
+4. **Check proxy settings** - Disable proxy if not required
+
+### Frontend Issues
+
+**"Frontend or Templates Package Not Updated":**
+```bash
+# After updating ComfyUI via Git, update frontend dependencies
+pip install -r requirements.txt
+```
+
+**"Can't Find Custom Node":**
+- Disable node validation in ComfyUI settings
+
+**"Error Toast About Workflow Failing Validation":**
+- Disable workflow validation in settings temporarily
+- Report the issue to the ComfyUI team
+
+**Login Issues When Not on Localhost:**
+- Normal login only works when accessing from localhost
+- For LAN/remote access: Generate API key at [platform.comfy.org/login](https://platform.comfy.org/login)
+- Use API key in login dialog or with `--api-key` command line argument
+
+## Hardware-Specific Issues
+
+### NVIDIA GPU Issues
+
+**"Torch not compiled with CUDA enabled" error:**
+```bash
+# First uninstall torch
+pip uninstall torch
+
+# Install stable PyTorch with CUDA 12.8
+pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu128
+
+# For nightly builds (might have performance improvements)
+pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu128
+
+# Verify CUDA support
+python -c "import torch; print(torch.cuda.is_available())"
+```
+
+**GPU not detected:**
+```bash
+# Check if GPU is visible
+nvidia-smi
+
+# Check driver version and CUDA compatibility
+nvidia-smi --query-gpu=driver_version --format=csv
+```
+
+### AMD GPU Issues
+
+**ROCm support (Linux only):**
+```bash
+# Install stable ROCm PyTorch (6.3.1 at the time of writing)
+pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.3
+
+# For nightly builds (ROCm 6.4 at the time of writing), which might have performance improvements)
+pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/rocm6.4
+```
+
+**Unsupported AMD GPUs:**
+```bash
+# For RDNA2 or older (6700, 6600)
+HSA_OVERRIDE_GFX_VERSION=10.3.0 python main.py
+
+# For RDNA3 cards (7600)
+HSA_OVERRIDE_GFX_VERSION=11.0.0 python main.py
+```
+
+**Performance optimization:**
+```bash
+# Enable experimental memory efficient attention (no longer necessary with PyTorch 2.4)
+TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1 python main.py --use-pytorch-cross-attention
+
+# Enable tunable operations (slow first run, but faster subsequent runs)
+PYTORCH_TUNABLEOP_ENABLED=1 python main.py
+```
+
+
+### Apple Silicon (M1/M2/M3) Issues
+
+**MPS backend setup:**
+```bash
+# Install PyTorch nightly for Apple Silicon
+# Follow Apple's guide: https://developer.apple.com/metal/pytorch/
+
+# Check MPS availability
+python -c "import torch; print(torch.backends.mps.is_available())"
+
+# Launch ComfyUI
+python main.py
+```
+
+**If MPS causes issues:**
+```bash
+# Force CPU mode
+python main.py --cpu
+
+# With memory optimization
+python main.py --force-fp16 --cpu
+```
+
+### Intel GPU Issues
+
+**Option 1: Native PyTorch XPU support (Windows/Linux):**
+```bash
+# Install PyTorch nightly with XPU support
+pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/xpu
+
+# Launch ComfyUI
+python main.py
+```
+
+**Option 2: Intel Extension for PyTorch (IPEX):**
+```bash
+# For Intel Arc A-Series Graphics
+conda install libuv
+pip install torch==2.3.1.post0+cxx11.abi torchvision==0.18.1.post0+cxx11.abi torchaudio==2.3.1.post0+cxx11.abi intel-extension-for-pytorch==2.3.110.post0+xpu --extra-index-url https://pytorch-extension.intel.com/release-whl/stable/xpu/us/
+```
+
+## Getting Help & Reporting Bugs
+
+### Before Reporting a Bug
+
+1. **Check if it's a known issue:**
+ - Search [GitHub Issues](https://github.com/comfyanonymous/ComfyUI/issues)
+ - Check [ComfyUI Forum](https://forum.comfy.org/)
+ - Review [Discord discussions](https://discord.com/invite/comfyorg)
+
+2. **Try basic troubleshooting:**
+ - Test with [default workflow](/get_started/first_generation)
+ - Disable all custom nodes (see [custom node troubleshooting](/troubleshooting/custom-node-issues))
+ - Check console/terminal for error messages
+ - If using comfy-cli, try updating: `comfy node update all`
+
+### How to Report Bugs Effectively
+
+#### For ComfyUI Core Issues
+**Where to report:** [GitHub Issues](https://github.com/comfyanonymous/ComfyUI/issues)
+
+#### For Desktop App Issues
+**Where to report:** [Desktop GitHub Issues](https://github.com/Comfy-Org/desktop/issues)
+
+#### For Frontend Issues
+**Where to report:** [Frontend GitHub Issues](https://github.com/Comfy-Org/ComfyUI_frontend/issues)
+
+#### For Custom Node Issues
+**Where to report:** Contact the specific custom node developer
+
+### Required Information
+
+When reporting any issue, include:
+
+
+
+
+
+
+**System Information (can be found in the About page in settings):**
+- Operating System (Windows 11, macOS 14.1, Ubuntu 22.04, etc.)
+- ComfyUI version (check About page in settings)
+- Python version: `python --version`
+- PyTorch version: `python -c "import torch; print(torch.__version__)"`
+- GPU model and driver version
+- Installation method (Desktop, Portable, Manual, comfy-cli)
+
+
+
+
+
+
+ ```bash
+ # System info
+ systeminfo | findstr /C:"OS Name" /C:"OS Version"
+
+ # GPU info
+ wmic path win32_VideoController get name
+
+ # Python & PyTorch info
+ python --version
+ python -c "import torch; print(f'PyTorch: {torch.__version__}')"
+ python -c "import torch; print(f'CUDA Available: {torch.cuda.is_available()}')"
+ ```
+
+
+ ```bash
+ # System info
+ uname -a
+
+ # GPU info (Linux)
+ lspci | grep VGA
+
+ # Python & PyTorch info
+ python --version
+ python -c "import torch; print(f'PyTorch: {torch.__version__}')"
+ python -c "import torch; print(f'CUDA Available: {torch.cuda.is_available()}')"
+ ```
+
+
+
+
+
+
+
+**For Desktop App issues, also include:**
+- Log files from: `C:\Users\\AppData\Roaming\ComfyUI\logs` (Windows)
+- Config files from: `C:\Users\\AppData\Roaming\ComfyUI` (Windows)
+
+
+
+**Problem Details:**
+- Clear description of the issue
+- Steps to reproduce the problem
+- Expected vs actual behavior
+- Screenshots or videos if applicable
+
+**Error Messages:**
+- Full error text from console/terminal
+- Browser console errors (F12 → Console tab)
+- Any crash logs or error dialogs
+
+
+
+**Additional Context:**
+- List of installed custom nodes
+- Workflow file (.json) that reproduces the issue
+- Recent changes (new installations, updates, etc.)
+
+
+
+## Community Resources
+
+- **Official Forum:** [forum.comfy.org](https://forum.comfy.org/)
+- **Discord:** [ComfyUI Discord Server](https://discord.com/invite/comfyorg)
+- **Reddit:** [r/comfyui](https://reddit.com/r/comfyui)
+- **YouTube:** [ComfyUI Tutorials](https://www.youtube.com/@comfyorg)
diff --git a/zh-CN/troubleshooting/custom-node-issues.mdx b/zh-CN/troubleshooting/custom-node-issues.mdx
new file mode 100644
index 000000000..ede63fcd6
--- /dev/null
+++ b/zh-CN/troubleshooting/custom-node-issues.mdx
@@ -0,0 +1,289 @@
+---
+title: "如何解决和排查 ComfyUI 中自定义节点导致的问题"
+description: "故障排除和修复由自定义节点和扩展引起的问题"
+icon: "puzzle-piece"
+sidebarTitle: "自定义节点问题"
+---
+
+## 快速问题诊断
+
+如果你遇到以下任何问题，很可能是由自定义节点引起的：
+- ComfyUI 崩溃或无法启动
+- 控制台/日志中出现"Failed to import"（导入失败）错误
+- UI 完全损坏或显示空白屏幕
+- "Prompt execution failed"（提示执行失败）错误
+- 应该可用的节点丢失
+
+## 这是自定义节点问题吗？
+
+大多数 ComfyUI 问题都是由自定义节点（扩展）引起的。让我们检查是否是这种情况。
+
+### 步骤 1：禁用所有自定义节点后测试
+
+在禁用所有自定义节点的情况下运行 ComfyUI：
+
+
+
+从设置菜单中启动禁用自定义节点的 ComfyUI 桌面版
+
+
+
+或手动运行服务器：
+
+```bash
+cd path/to/your/comfyui
+python main.py --disable-all-custom-nodes
+```
+
+
+```bash
+cd ComfyUI
+python main.py --disable-all-custom-nodes
+```
+
+
+
+
+
+ 打开便携版所在的文件夹，找到 `run_nvidia_gpu.bat` 或者 `run_cpu.bat` 文件
+
+ 
+ 1. 复制 `run_nvidia_gpu.bat` 或者 `run_cpu.bat` 文件并重命名为 `run_nvidia_gpu_disable_custom_nodes.bat`
+ 2. 使用记事本打开复制后的文件
+ 3. 在文件中添加 `--disable-all-custom-nodes` 参数，或者复制下面的参数保存到 txt 文件中后将文件后缀名改为 `.bat`
+
+ ```bash
+ .\python_embeded\python.exe -s ComfyUI\main.py --disable-all-custom-nodes --windows-standalone-build
+ pause
+ ```
+ 4. 保存文件并关闭
+ 5. 双击运行文件，如果一切正常，你应该会看到 ComfyUI 启动，并且自定义节点被禁用
+
+
+ 
+ 1. 进入便携版所在的文件夹
+ 2. 通过右键菜单 → 打开终端 来打开命令行
+
+ 
+
+ 3. 确保在命令行中文件夹名称是当前便携版所在的文件目录
+ 4. 输入以下命令,来通过便携版的 python 来启动 ComfyUI 并禁用自定义节点
+ ```
+ .\python_embeded\python.exe -s ComfyUI\main.py --disable-all-custom-nodes
+ ```
+
+
+
+
+
+**结果：**
+- ✅ **问题消失**：自定义节点导致问题 → 继续步骤 2
+- ❌ **问题仍然存在**：不是自定义节点问题 → [报告问题](#报告问题)
+
+## 步骤 2：找到有问题的自定义节点
+
+我们将使用**二分搜索**快速找到哪个自定义节点导致问题。这比逐个测试节点要快得多。
+
+### 二分搜索的工作原理
+
+我们不是逐个测试每个节点（可能需要几个小时），而是反复将节点分成两半：
+
+```
+8 个节点 → 测试 4 个节点 → 测试 2 个节点 → 测试 1 个节点 ✓
+
+8 个节点的示例：
+1. 测试节点 1-4：问题仍然存在 ✓ → 问题在剩余节点 5-8 中
+2. 测试节点 5-6：问题消失 ✓ → 问题在节点 7-8 中
+3. 测试节点 7：问题仍然存在 ✓ → 节点 7 是问题所在！
+
+这只需要 3 次测试，而不是测试所有 8 个节点。
+```
+
+### 二分搜索过程
+
+
+开始之前，请**创建备份**你的 custom_nodes 文件夹，以防出现问题。
+
+
+#### 创建临时文件夹
+
+
+
+```bash
+# 创建备份和临时文件夹
+mkdir "%USERPROFILE%\custom_nodes_backup"
+mkdir "%USERPROFILE%\custom_nodes_temp"
+
+# 首先备份所有内容
+xcopy "custom_nodes\*" "%USERPROFILE%\custom_nodes_backup\" /E /H /Y
+```
+
+
+```bash
+# 创建备份和临时文件夹
+mkdir ~/custom_nodes_backup
+mkdir ~/custom_nodes_temp
+
+# 首先备份所有内容
+cp -r custom_nodes/* ~/custom_nodes_backup/
+```
+
+
+```bash
+# 创建备份和临时文件夹
+mkdir /content/custom_nodes_backup
+mkdir /content/custom_nodes_temp
+
+# 首先备份所有内容
+cp -r /content/ComfyUI/custom_nodes/* /content/custom_nodes_backup/
+```
+
+
+
+#### 找到有问题的节点
+
+1. **列出你的自定义节点：**
+
+
+ ```bash
+ dir custom_nodes
+ ```
+
+
+ ```bash
+ ls custom_nodes/
+ ```
+
+
+ ```bash
+ ls /content/ComfyUI/custom_nodes/
+ ```
+
+
+
+2. **将节点分成两半：**
+
+ 假设你有 8 个自定义节点。将前一半移动到临时存储：
+
+
+
+ ```bash
+ # 将前一半（节点 1-4）移动到临时文件夹
+ move "custom_nodes\node1" "%USERPROFILE%\custom_nodes_temp\"
+ move "custom_nodes\node2" "%USERPROFILE%\custom_nodes_temp\"
+ move "custom_nodes\node3" "%USERPROFILE%\custom_nodes_temp\"
+ move "custom_nodes\node4" "%USERPROFILE%\custom_nodes_temp\"
+ ```
+
+
+ ```bash
+ # 将前一半（节点 1-4）移动到临时文件夹
+ mv custom_nodes/node1 ~/custom_nodes_temp/
+ mv custom_nodes/node2 ~/custom_nodes_temp/
+ mv custom_nodes/node3 ~/custom_nodes_temp/
+ mv custom_nodes/node4 ~/custom_nodes_temp/
+ ```
+
+
+ ```bash
+ # 将前一半（节点 1-4）移动到临时文件夹
+ mv /content/ComfyUI/custom_nodes/node1 /content/custom_nodes_temp/
+ mv /content/ComfyUI/custom_nodes/node2 /content/custom_nodes_temp/
+ mv /content/ComfyUI/custom_nodes/node3 /content/custom_nodes_temp/
+ mv /content/ComfyUI/custom_nodes/node4 /content/custom_nodes_temp/
+ ```
+
+
+
+3. **测试 ComfyUI：**
+ ```bash
+ python main.py
+ ```
+
+4. **解释结果：**
+ - **问题仍然存在**：问题在剩余节点（5-8）中
+ - **问题消失**：问题在移动的节点（1-4）中
+
+5. **缩小范围：**
+ - 如果问题仍然存在：将剩余节点的一半（例如节点 7-8）移动到临时文件夹
+ - 如果问题消失：将临时节点的一半（例如节点 3-4）移回 custom_nodes
+
+6. **重复直到找到单个有问题的节点**
+
+### 视觉示例
+
+让我们通过一个包含 8 个自定义节点的完整示例：
+
+```
+📁 custom_nodes/
+├── 🔧 ComfyUI-Manager
+├── 🎨 ComfyUI-Custom-Scripts
+├── 🖼️ ComfyUI-Impact-Pack
+├── 🔄 ComfyUI-Workflow-Component
+├── 📊 ComfyUI-AnimateDiff-Evolved
+├── 🎭 ComfyUI-FaceRestore
+├── ⚡ ComfyUI-Advanced-ControlNet
+└── 🛠️ ComfyUI-Inspire-Pack
+```
+
+**第 1 轮：** 将前 4 个移动到临时文件夹
+- 测试 → 问题仍然存在 ✓
+- 问题在：ComfyUI-AnimateDiff-Evolved、ComfyUI-FaceRestore、ComfyUI-Advanced-ControlNet、ComfyUI-Inspire-Pack
+
+**第 2 轮：** 将剩余 4 个中的 2 个移动到临时文件夹
+- 测试 → 问题消失 ✓
+- 问题在：ComfyUI-Advanced-ControlNet、ComfyUI-Inspire-Pack
+
+**第 3 轮：** 将剩余 2 个中的 1 个移动到临时文件夹
+- 测试 → 问题仍然存在 ✓
+- **找到了！** ComfyUI-Inspire-Pack 是有问题的节点
+
+## 步骤 3：修复问题
+
+一旦你识别出有问题的自定义节点：
+
+### 选项 1：更新节点
+1. 检查 ComfyUI 管理器中是否有可用更新
+2. 更新节点并再次测试
+
+### 选项 2：替换节点
+1. 寻找具有类似功能的替代自定义节点
+2. 查看 [ComfyUI 注册表](https://registry.comfy.org) 寻找替代方案
+
+### 选项 3：报告问题
+联系自定义节点开发者：
+1. 找到节点的 GitHub 仓库
+2. 创建问题并包含：
+ - 你的 ComfyUI 版本
+ - 错误消息/日志
+ - 重现步骤
+ - 你的操作系统
+
+### 选项 4：移除节点
+如果没有修复可用且你不需要该功能：
+1. 从 `custom_nodes/` 中移除有问题的节点
+2. 重启 ComfyUI
+
+## 报告问题
+
+如果问题不是由自定义节点引起的，请参考通用[故障排除概述](/zh-CN/troubleshooting/overview)了解其他常见问题。
+
+### 自定义节点特定问题
+联系自定义节点开发者：
+- 找到节点的 GitHub 仓库
+- 创建问题并包含你的 ComfyUI 版本、错误消息、重现步骤和操作系统
+- 查看节点文档了解已知问题
+
+### ComfyUI 核心问题
+- **GitHub**：[ComfyUI Issues](https://github.com/comfyanonymous/ComfyUI/issues)
+- **论坛**：[官方 ComfyUI 论坛](https://forum.comfy.org/)
+
+### 桌面应用问题
+- **GitHub**：[ComfyUI 桌面问题](https://github.com/Comfy-Org/desktop/issues)
+
+### 前端问题
+- **GitHub**：[ComfyUI 前端问题](https://github.com/Comfy-Org/ComfyUI_frontend/issues)
+
+
+对于一般安装、模型或性能问题，请参见我们的[故障排除概述](/zh-CN/troubleshooting/overview)和[模型问题](/zh-CN/troubleshooting/model-issues)页面。
+
\ No newline at end of file
diff --git a/zh-CN/troubleshooting/model-issues.mdx b/zh-CN/troubleshooting/model-issues.mdx
new file mode 100644
index 000000000..20ab42c74
--- /dev/null
+++ b/zh-CN/troubleshooting/model-issues.mdx
@@ -0,0 +1,145 @@
+---
+title: "如何排查和解决 ComfyUI 中模型相关的问题"
+description: "故障排除模型相关问题，包括架构不匹配、缺少模型和加载错误"
+icon: "cube"
+sidebarTitle: "模型问题"
+---
+
+## 模型架构不匹配
+
+**症状：** 生成过程中出现张量维度错误，特别是在 VAE 解码阶段
+
+**常见错误消息：**
+- `Given groups=1, weight of size [64, 4, 3, 3], expected input[1, 16, 128, 128] to have 4 channels, but got 16 channels instead`
+- `Given groups=1, weight of size [4, 4, 1, 1], expected input[1, 16, 144, 112] to have 4 channels, but got 16 channels instead`
+- `Given groups=1, weight of size [320, 4, 3, 3], expected input[2, 16, 192, 128] to have 4 channels, but got 16 channels instead`
+
+**根本原因：** 将来自不同架构系列的模型混合使用
+
+### 解决方案
+
+1. **验证模型系列兼容性：**
+ - **Flux 模型**使用 16 通道潜在空间，配合双文本编码器调节（CLIP-L + T5-XXL）
+ - **SD1.5 模型**使用 4 通道潜在空间，配合单个 CLIP ViT-L/14 文本编码器
+ - **SDXL 模型**使用 4 通道潜在空间，配合双文本编码器（CLIP ViT-L/14 + OpenCLIP ViT-bigG/14）
+ - **SD3 模型**使用 16 通道潜在空间，配合三重文本编码器调节（CLIP-L + OpenCLIP bigG + T5-XXL）
+
+2. **常见不匹配场景和修复：**
+
+ **Flux + 错误的 VAE：**
+ ```
+ 问题：将 taesd 或 sdxl_vae.safetensors 与 Flux 检查点一起使用
+ 修复：使用来自 Hugging Face Flux 发布的 ae.safetensors（Flux VAE）
+ ```
+
+ **Flux + 不正确的 CLIP 配置：**
+ ```
+ 问题：在 DualClipLoader 的两个 CLIP 插槽中都使用 t5xxl_fp8_e4m3fn.safetensors
+ 修复：在一个插槽中使用 t5xxl_fp8_e4m3fn.safetensors，在另一个插槽中使用 clip_l.safetensors
+ ```
+
+ **ControlNet 架构不匹配：**
+ ```
+ 问题：SD1.5 ControlNet 与不同架构检查点
+ 修复：使用为您的检查点架构设计的 ControlNet 模型
+ ```
+
+3. **快速诊断：**
+ ```bash
+ # 检查错误是否发生在 VAE 解码阶段
+ # 寻找 "expected input[X, Y, Z] to have N channels, but got M channels"
+ # Y 值表示通道数：4 = SD 模型，16 = Flux 模型
+ ```
+
+4. **预防策略：**
+ - 将所有工作流模型保持在同一架构系列内
+ - 从同一来源/发布下载完整的模型包
+ - 使用 ComfyUI 管理器的模型兼容性指示器
+ - 在自定义之前使用默认示例测试工作流
+
+## 缺少模型错误
+
+**错误消息：**
+```
+Prompt execution failed
+Prompt outputs failed validation:
+CheckpointLoaderSimple:
+- Value not in list: ckpt_name: 'model-name.safetensors' not in []
+```
+
+### 解决方案
+
+1. **下载所需模型：**
+ - 使用 ComfyUI 管理器自动下载模型
+ - 验证模型在正确的子文件夹中
+
+2. **检查模型路径：**
+ - **检查点**：`models/checkpoints/`
+ - **VAE**：`models/vae/`
+ - **LoRA**：`models/loras/`
+ - **ControlNet**：`models/controlnet/`
+ - **嵌入**：`models/embeddings/`
+
+3. **在 UI 之间共享模型或使用自定义路径：**
+ - 参见 [ComfyUI 模型共享或自定义模型文件夹存储位置配置](/zh-CN/installation/comfyui_portable_windows#2-comfyui-模型共享或自定义模型文件夹存储位置配置) 获取详细说明
+ - 编辑 `extra_model_paths.yaml` 文件添加自定义模型目录
+
+### 模型搜索路径配置
+
+如果您的模型在自定义位置，请参见详细的 [ComfyUI 模型共享或自定义模型文件夹存储位置配置](/zh-CN/installation/comfyui_portable_windows#2-comfyui-模型共享或自定义模型文件夹存储位置配置) 指南来配置 ComfyUI 找到它们。
+
+## 模型加载错误
+
+**错误消息：** "Error while deserializing header"
+
+### 解决方案
+
+1. **重新下载模型** - 下载过程中文件可能已损坏
+2. **检查可用磁盘空间** - 确保有足够的空间用于模型加载（模型可能 2-15GB+）
+3. **检查文件权限** - 确保 ComfyUI 可以读取模型文件
+4. **使用不同模型测试** - 验证问题是模型特定的还是系统范围的
+
+## 模型性能问题
+
+### 模型加载缓慢
+
+**症状：** 切换模型或开始生成时长时间延迟
+
+**解决方案：**
+1. **将模型保持在显存中：**
+ ```bash
+ python main.py --highvram
+ ```
+
+2. **使用更快的存储：**
+ - 如果使用 HDD，将模型移至 SSD
+ - 使用 NVMe SSD 获得最佳性能
+
+3. **调整缓存设置：**
+ ```bash
+ python main.py --cache-classic # 使用旧式（积极）缓存
+ ```
+
+### 大型模型的内存问题
+
+**"RuntimeError: CUDA out of memory"：**
+
+```bash
+# 渐进式内存减少
+python main.py --lowvram # 首先尝试
+python main.py --novram # 如果 lowvram 不够
+python main.py --cpu # 最后手段
+```
+
+**模型特定的内存优化：**
+```bash
+# 强制更低精度
+python main.py --force-fp16
+
+# 减少注意力内存使用
+python main.py --use-pytorch-cross-attention
+```
+
+
+有关其他模型配置和设置信息，请参见[模型文档](/zh-CN/development/core-concepts/models)。
+
\ No newline at end of file
diff --git a/zh-CN/troubleshooting/overview.mdx b/zh-CN/troubleshooting/overview.mdx
new file mode 100644
index 000000000..45c5ff9f9
--- /dev/null
+++ b/zh-CN/troubleshooting/overview.mdx
@@ -0,0 +1,387 @@
+---
+title: "如何排查和解决 ComfyUI 中出现的错误"
+description: "常见 ComfyUI 问题、解决方案和如何有效报告错误"
+icon: "lightbulb"
+sidebarTitle: "概述"
+---
+
+
+ 我们日常收到的诸多反馈问题，我们发现绝大部分的问题提交都与自定义节点有关,所以在提交对应的错误反馈之前，请你确保详细阅读了 [自定义节点故障排除](/zh-CN/troubleshooting/custom-node-issues) 部分的指南，来确保对应的问题并不是由 ComfyUI 核心问题导致的。
+
+
+
+ 查看如何排查自定义节点导致的问题。
+
+
+## 常见问题与快速修复
+
+在深入详细故障排除之前，请尝试这些常见解决方案：
+
+### ComfyUI 无法启动
+
+**症状：** 应用程序在启动时崩溃、黑屏或无法加载
+
+**快速修复：**
+1. **检查系统要求** - 确保您的系统符合[最低要求](/zh-CN/installation/system_requirements)
+2. **更新 GPU 驱动程序** - 从 NVIDIA/AMD/Intel 下载最新驱动程序
+
+### 生成失败或产生错误
+
+**症状：** "Prompt execution failed"（提示执行失败）对话框，带有"Show report"（显示报告）按钮，工作流停止执行
+
+**快速修复：**
+1. **点击"Show report"** - 阅读详细错误消息以识别具体问题
+2. **检查是否是自定义节点问题** - [遵循我们的自定义节点故障排除指南](/zh-CN/troubleshooting/custom-node-issues)
+3. **验证模型文件** - 查看[模型文档](/zh-CN/development/core-concepts/models)了解模型设置
+4. **检查显存使用情况** - 关闭其他使用 GPU 内存的应用程序
+
+### 性能缓慢
+
+**症状：** 生成时间非常慢、系统冻结、内存不足错误
+
+**快速修复：**
+1. **降低分辨率/批次大小** - 减少图像大小或图像数量
+2. **使用内存优化标志** - 请参见下方性能优化部分
+3. **关闭不必要的应用程序** - 释放 RAM 和显存
+4. **检查 CPU/GPU 使用率** - 使用任务管理器识别瓶颈
+
+**性能优化命令：**
+
+对于低显存系统：
+```bash
+# 低显存模式（将模型分成多个部分）
+python main.py --lowvram
+
+# 当 --lowvram 不够用时的更低显存模式
+python main.py --novram
+
+# CPU 模式（非常慢但适用于任何硬件）
+python main.py --cpu
+```
+
+提高性能：
+```bash
+# 禁用预览（节省显存和处理）
+python main.py --preview-method none
+
+# 将模型保持在显存中（更快但使用更多显存）
+python main.py --highvram
+
+# 强制 FP16 精度（更快，使用更少显存）
+python main.py --force-fp16
+
+# 使用优化的注意力机制
+python main.py --use-pytorch-cross-attention
+python main.py --use-flash-attention
+
+# 异步权重卸载
+python main.py --async-offload
+```
+
+内存管理：
+```bash
+# 为操作系统保留特定显存量（以 GB 为单位）
+python main.py --reserve-vram 2
+
+# 禁用智能内存管理
+python main.py --disable-smart-memory
+
+# 使用不同的缓存策略
+python main.py --cache-none # 更少的内存使用
+python main.py --cache-lru 10 # 缓存 10 个结果
+```
+
+## 安装过程中出现的问题
+
+### 桌面应用问题
+
+有关全面的桌面安装故障排除，请参见[桌面安装指南](/zh-CN/installation/desktop/windows)。
+
+
+
+- **无法安装**：以管理员身份运行安装程序
+- **缺少依赖项**：安装 [Visual C++ 可再发行组件](https://aka.ms/vs/17/release/vc_redist.x64.exe)
+- **启动时崩溃**：检查 Windows 事件查看器以获取错误详细信息
+
+
+- **"应用程序已损坏"**：在安全性与隐私设置中允许应用程序
+- **性能问题**：在隐私设置中授予完整磁盘访问权限
+- **崩溃**：检查控制台应用程序以获取崩溃报告
+
+
+- **缺少库**：使用包管理器安装依赖项
+- **LD_LIBRARY_PATH 错误**：PyTorch 库路径问题（见下文）
+
+
+
+### 手动安装问题
+
+
+文档可能略有过时。如果出现问题，请手动验证是否存在更新的稳定版本的 pytorch 或任何列出的库。请参考 [pytorch 安装矩阵](https://pytorch.org/get-started/locally/) 或 [ROCm 网站](https://rocm.docs.amd.com/projects/install-on-linux/en/develop/install/3rd-party/pytorch-install.html#using-a-wheels-package) 等资源。
+
+
+**Python 版本冲突：**
+```bash
+# 检查 Python 版本（需要 3.9+，推荐 3.12）
+python --version
+
+# 使用虚拟环境（推荐）
+python -m venv comfyui_env
+source comfyui_env/bin/activate # Linux/Mac
+comfyui_env\Scripts\activate # Windows
+```
+
+**包安装失败：**
+```bash
+# 首先更新 pip
+python -m pip install --upgrade pip
+
+# 安装依赖项
+pip install -r requirements.txt
+
+# 对于 NVIDIA GPU（CUDA 12.8）
+pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu128
+
+# 对于 AMD GPU（仅限 Linux - ROCm 6.3）
+pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.3
+```
+
+### Linux 特定问题
+
+**LD_LIBRARY_PATH 错误：**
+
+常见错误：
+- "libcuda.so.1: cannot open shared object file"
+- "libnccl.so: cannot open shared object file"
+- "ImportError: libnvinfer.so.X: cannot open shared object file"
+
+**解决方案：**
+
+1. **现代 PyTorch 安装（最常见）：**
+```bash
+# 对于带有 NVIDIA 包的虚拟环境
+export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib/python3.12/site-packages/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH
+
+# 对于 conda 环境
+export LD_LIBRARY_PATH=$CONDA_PREFIX/lib/python3.12/site-packages/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH
+
+# 或自动查找您的 Python site-packages
+PYTHON_PATH=$(python -c "import site; print(site.getsitepackages()[0])")
+export LD_LIBRARY_PATH=$PYTHON_PATH/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH
+
+# 您可能还需要其他 NVIDIA 库
+export LD_LIBRARY_PATH=$PYTHON_PATH/nvidia/cuda_runtime/lib:$LD_LIBRARY_PATH
+export LD_LIBRARY_PATH=$PYTHON_PATH/nvidia/cublas/lib:$LD_LIBRARY_PATH
+```
+
+2. **查找你拥有的库：**
+```bash
+# 检查已安装的 NVIDIA 包
+python -c "import site; import os; nvidia_path=os.path.join(site.getsitepackages()[0], 'nvidia'); print('NVIDIA libs:', [d for d in os.listdir(nvidia_path) if os.path.isdir(os.path.join(nvidia_path, d))] if os.path.exists(nvidia_path) else 'Not found')"
+
+# 查找 PyTorch 需要的缺失库
+python -c "import torch; print(torch.__file__)"
+ldd $(python -c "import torch; print(torch.__file__.replace('__init__.py', 'lib/libtorch_cuda.so'))")
+```
+
+3. **为你的环境永久设置：**
+```bash
+# 对于虚拟环境，添加到激活脚本
+echo 'export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib/python*/site-packages/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH' >> $VIRTUAL_ENV/bin/activate
+
+# 对于 conda 环境
+conda env config vars set LD_LIBRARY_PATH=$CONDA_PREFIX/lib/python*/site-packages/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH
+
+# 对于全局 bashrc（根据需要调整 Python 版本）
+echo 'export LD_LIBRARY_PATH=$(python -c "import site; print(site.getsitepackages()[0])")/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH' >> ~/.bashrc
+```
+
+4. **替代方案：使用 ldconfig：**
+```bash
+# 检查当前库缓存
+ldconfig -p | grep cuda
+ldconfig -p | grep nccl
+
+# 如果缺失，添加库路径（需要 root 权限）
+sudo echo "/usr/local/cuda/lib64" > /etc/ld.so.conf.d/cuda.conf
+sudo ldconfig
+```
+
+5. **调试库加载：**
+```bash
+# 详细库加载以查看缺失的内容
+LD_DEBUG=libs python main.py 2>&1 | grep "looking for"
+
+# 检查 PyTorch CUDA 可用性
+python -c "import torch; print('CUDA available:', torch.cuda.is_available()); print('CUDA version:', torch.version.cuda)"
+```
+
+## 模型相关问题
+
+有关综合模型故障排除，包括架构不匹配、缺少模型和加载错误，请参见专门的[模型问题](/zh-CN/troubleshooting/model-issues)页面。
+
+## 网络和 API 问题
+
+### API 节点不工作
+
+**症状：** API 调用失败、超时错误、配额超出
+
+**解决方案：**
+1. **检查 API 密钥有效性** - 在[用户设置](/zh-CN/interface/user)中验证密钥
+2. **检查账户积分** - 确保有足够的 [API 积分](/zh-CN/interface/credits)
+3. **验证互联网连接** - 使用其他在线服务进行测试
+4. **检查服务状态** - 提供商可能正在经历停机
+
+### 连接问题
+
+**症状：** "无法连接到服务器"、超时错误
+
+**解决方案：**
+1. **检查防火墙设置** - 允许 ComfyUI 通过防火墙
+2. **尝试不同端口** - 默认是 8188，尝试 8189 或 8190
+3. **临时禁用 VPN** - VPN 可能阻止连接
+4. **检查代理设置** - 如果不需要，禁用代理
+
+## 硬件特定问题
+
+### NVIDIA GPU 问题
+
+**CUDA 错误、GPU 未检测到：**
+```bash
+# 检查 CUDA 安装
+nvidia-smi
+
+# 验证 PyTorch CUDA 支持
+python -c "import torch; print(torch.cuda.is_available())"
+
+# 重新安装带 CUDA 的 PyTorch
+pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
+```
+
+### AMD GPU 问题
+
+**ROCm 支持、性能问题：**
+```bash
+# 安装 ROCm 版本的 PyTorch
+pip install torch torchvision --index-url https://download.pytorch.org/whl/rocm5.7
+```
+
+### Apple Silicon (M1/M2/M3) 问题
+
+**MPS 后端错误：**
+```bash
+# 检查 MPS 可用性
+python -c "import torch; print(torch.backends.mps.is_available())"
+
+# 如果 MPS 导致问题，强制使用 CPU
+python main.py --force-fp16 --cpu
+```
+
+## 获取帮助和报告错误
+
+### 报告错误之前
+
+1. **检查是否是已知问题：**
+ - 搜索 [GitHub Issues](https://github.com/comfyanonymous/ComfyUI/issues)
+ - 检查 [ComfyUI 论坛](https://forum.comfy.org/)
+ - 查看 [Discord 讨论](https://discord.com/invite/comfyorg)
+
+2. **尝试基本故障排除：**
+ - 使用[默认工作流](/zh-CN/get_started/first_generation)进行测试
+ - 禁用所有自定义节点（参见[自定义节点故障排除](/zh-CN/troubleshooting/custom-node-issues)）
+ - 检查控制台/终端中的错误消息
+
+### 如何有效报告错误
+
+#### 对于 ComfyUI 核心问题
+**问题提交：** [GitHub Issues](https://github.com/comfyanonymous/ComfyUI/issues)
+
+#### 对于桌面应用问题
+**问题提交：** [桌面 GitHub Issues](https://github.com/Comfy-Org/desktop/issues)
+
+#### 对于前端问题
+**问题提交：** [前端 GitHub Issues](https://github.com/Comfy-Org/ComfyUI_frontend/issues)
+
+#### 对于自定义节点问题
+**问题提交：** 请到对应的自定义节点仓库中提交问题
+
+### 在 issue 中你需要提供的信息
+
+报告任何问题时，请包括以下内容：
+
+
+
+
+
+
+ - 操作系统（Windows 11、macOS 14.1、Ubuntu 22.04 等）
+ - ComfyUI 版本（检查设置中的关于页面）
+ - Python 版本：`python --version`
+ - PyTorch 版本：`python -c "import torch; print(torch.__version__)"`
+ - GPU 型号和驱动程序版本
+
+ 
+
+
+
+
+ ```bash
+ # 系统信息
+ systeminfo | findstr /C:"OS Name" /C:"OS Version"
+
+ # GPU 信息
+ wmic path win32_VideoController get name
+
+ # Python 和 PyTorch 信息
+ python --version
+ python -c "import torch; print(f'PyTorch: {torch.__version__}')"
+ python -c "import torch; print(f'CUDA Available: {torch.cuda.is_available()}')"
+ ```
+
+
+ ```bash
+ # 系统信息
+ uname -a
+
+ # GPU 信息（Linux）
+ lspci | grep VGA
+
+ # Python 和 PyTorch 信息
+ python --version
+ python -c "import torch; print(f'PyTorch: {torch.__version__}')"
+ python -c "import torch; print(f'CUDA Available: {torch.cuda.is_available()}')"
+ ```
+
+
+
+
+
+
+
+ - 问题的清晰描述
+ - 重现问题的步骤
+ - 预期行为与实际行为
+ - 如果可以，提供截图或复现过程的屏幕录制
+
+
+ - 控制台/终端的完整错误文本
+ - 浏览器控制台错误（F12 → 控制台选项卡）
+ - 任何崩溃日志或错误对话框
+
+
+ - 已安装的自定义节点列表
+ - 重现问题的工作流文件（.json）
+ - 最近的更改（新安装、更新等）
+
+
+
+## 社区资源
+
+- **官方论坛：** [forum.comfy.org](https://forum.comfy.org/)
+- **Discord：** [ComfyUI Discord 服务器](https://discord.com/invite/comfyorg)
+- **Reddit：** [r/comfyui](https://reddit.com/r/comfyui)
+- **YouTube：** [ComfyUI 教程](https://www.youtube.com/@comfyorg)
+
+
+对于影响许多用户的紧急问题，请查看我们的[状态页面](https://status.comfy.org)和[官方 Twitter](https://x.com/ComfyUI)以获取公告。
+
\ No newline at end of file