Skip to content

Add the hyperlinks to the flowchart. #277

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
comfyui-wiki merged 1 commit into from
Jul 24, 2025
Merged

Add the hyperlinks to the flowchart. #277

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 65 additions & 77 deletions troubleshooting/custom-node-issues.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,23 +10,71 @@ Here is the overall approach for troubleshooting custom node issues:

```mermaid
flowchart TD
A[Issue Encountered] --> B{Does the issue disappear after disabling all custom nodes?}
A[Issue Encountered] --> B{Does the issue disappear after <a href="#how-to-disable-all-custom-nodes%3F">disabling all custom nodes</a>?}
B -- Yes --> C[Issue caused by custom nodes]
B -- No --> D[Issue not caused by custom nodes, refer to other troubleshooting docs]
C --> E{Check frontend extensions first?}
E -- Yes --> F[Troubleshoot in ComfyUI frontend]
E -- No --> G[Use general binary search method]
C --> E{<a href="#1-troubleshooting-the-custom-nodes’-frontend-extensions">Check frontend extensions first</a>?}
E -- Yes --> F[<a href="#1-troubleshooting-the-custom-nodes’-frontend-extensions">Troubleshoot in ComfyUI frontend</a><br/><li>Only need reload the frontend</li>]
E -- No --> G[<a href="#2-general-custom-node-troubleshooting">Use general binary search method</a><li>Need to restart ComfyUI multiple times</li>]
F --> H[Use binary search to locate problematic node]
G --> H
H --> I[Fix, replace, report or remove problematic node]
H --> I[<a href="#how-to-fix-the-issue">Fix, replace, report or remove problematic node</a>]
I --> J[Issue solved]
```

## How to determine if custom nodes are causing the issue?
## How to disable all custom nodes?

If the problem disappears after disabling all custom nodes, we can determine that the issue is caused by custom nodes.
<Tabs>
<Tab title="Desktop Users">
Start ComfyUI Desktop with custom nodes disabled from the settings menu
![Settings menu - Disable custom nodes](/images/troubleshooting/desktop-diable-custom-node.jpg)
or run the server manually:
```bash
cd path/to/your/comfyui
python main.py --disable-all-custom-nodes
```
</Tab>
<Tab title="Manual Install">
```bash
cd ComfyUI
python main.py --disable-all-custom-nodes
```
</Tab>
<Tab title="Portable">
<Tabs>
<Tab title="Modify `.bat` file">
Open the folder where the portable version is located, and find the `run_nvidia_gpu.bat` or `run_cpu.bat` file
![Modify .bat file](/images/troubleshooting/Portable-disable-custom-nodes.jpg)
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
</Tab>
<Tab title="Through Command Line">
![ComfyUI troubleshooting](/images/troubleshooting/portable-disable-custom-nodes-cml-1.jpg)
1. Enter the folder where the portable version is located
2. Open the terminal by right-clicking the menu → Open terminal
![ComfyUI troubleshooting](/images/troubleshooting/portable-disable-custom-nodes-cml-2.jpg)
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
```
</Tab>
</Tabs>
</Tab>
</Tabs>

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

### Binary search troubleshooting approach
## What is Binary Search?

In this document, we will introduce the binary search approach for troubleshooting custom node issues, which involves checking half of the custom nodes at a time until we locate the problematic node.

Expand All @@ -50,7 +98,7 @@ flowchart TD
K --> B
L --> M[End]
```
## Different Troubleshooting Methods for Different Types of Custom Node Issues
## Two Troubleshooting Methods

In this document, we categorize custom nodes into two types for troubleshooting:

Expand All @@ -61,8 +109,8 @@ In this document, we categorize custom nodes into two types for troubleshooting:
Let's first understand the potential issues and causes for different types of custom nodes:

<Tabs>
<Tab title="Issues with Frontend Extension Custom Nodes">
For custom nodes, we need to prioritize troubleshooting those with frontend extensions, as they cause the most issues. Their main conflicts arise from incompatibilities with ComfyUI frontend version updates.
<Tab title="Custom Nodes with Frontend Extensions">
For custom nodes, we can prioritize troubleshooting those with frontend extensions, as they cause the most issues. Their main conflicts arise from incompatibilities with ComfyUI frontend version updates.

Common issues include:
- Workflows not executing
Expand All @@ -80,8 +128,8 @@ Let's first understand the potential issues and causes for different types of cu
- Authors stopping maintenance, leading to incompatibility between custom node extensions and the ComfyUI frontend

</Tab>
<Tab title="Regular Custom Node Issues">
If the problem isn't caused by frontend extensions, issues often relate to dependencies. Common problems include:
<Tab title="Regular Custom Nodes">
If the problem isn't caused by custom nodes' frontend extensions, issues often relate to dependencies. Common problems include:
- "Failed to import" errors in console/logs
- Missing nodes still showing as missing after installation and restart
- ComfyUI crashes or fails to start
Expand All @@ -100,10 +148,10 @@ Let's first understand the potential issues and causes for different types of cu

Among these two different types of custom node issues, conflicts between custom node frontend extensions and ComfyUI are more common. We'll prioritize troubleshooting these nodes first. Here's the overall troubleshooting approach:

### 1. Troubleshooting Custom Nodes with Frontend Extensions
### 1. Troubleshooting the Custom Nodes' Frontend Extensions

<Steps>
<Step title="Disable All Plugin Frontend Extensions">
<Step title="Disable All Third-Party Frontend Extensions">
![Disable all plugin frontend extensions](/images/troubleshooting/disable_3rd_party.jpg)
After starting ComfyUI, find the `Extensions` menu in settings and follow the steps shown in the image to disable all third-party extensions
<Tip>
Expand All @@ -127,71 +175,11 @@ Among these two different types of custom node issues, conflicts between custom

Using this method, you don't need to restart ComfyUI multiple times - just reload ComfyUI after enabling/disabling custom node frontend extensions. Plus, your troubleshooting scope is limited to nodes with frontend extensions, which greatly narrows down the search range.

### 2. General Custom Node Troubleshooting Approach
### 2. General Custom Node Troubleshooting


<Steps>
<Step title="Test with all custom nodes disabled">
<Tabs>
<Tab title="Desktop Users">
Start ComfyUI Desktop with custom nodes disabled from the settings menu

![Settings menu - Disable custom nodes](/images/troubleshooting/desktop-diable-custom-node.jpg)

or run the server manually:

```bash
cd path/to/your/comfyui
python main.py --disable-all-custom-nodes
```
</Tab>
<Tab title="Manual Install">
```bash
cd ComfyUI
python main.py --disable-all-custom-nodes
```
</Tab>
<Tab title="Portable">
<Tabs>
<Tab title="Modify `.bat` file">
Open the folder where the portable version is located, and find the `run_nvidia_gpu.bat` or `run_cpu.bat` file

![Modify .bat file](/images/troubleshooting/Portable-disable-custom-nodes.jpg)
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
</Tab>
<Tab title="Through Command Line">
![ComfyUI troubleshooting](/images/troubleshooting/portable-disable-custom-nodes-cml-1.jpg)
1. Enter the folder where the portable version is located
2. Open the terminal by right-clicking the menu → Open terminal

![ComfyUI troubleshooting](/images/troubleshooting/portable-disable-custom-nodes-cml-2.jpg)

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
```
</Tab>
</Tabs>
</Tab>

</Tabs>

**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>
<Step title="Use Binary Search to Locate Custom Nodes">
<Step title="Use Binary Search to Locate Custom Nodes">
For the binary search localization method, in addition to manual search, we also have automated binary search using comfy-cli, as detailed below:

<Tabs>
Expand Down
130 changes: 60 additions & 70 deletions zh-CN/troubleshooting/custom-node-issues.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,23 +9,72 @@ sidebarTitle: "自定义节点问题"

```mermaid
flowchart TD
A[遇到问题] --> B{禁用所有自定义节点后问题是否消失？}
A[遇到问题] --> B{<a href="#如何禁用所有的自定义节点？">禁用所有自定义节点后问题是否消失？</a>}
B -- 是 --> C[问题由自定义节点引起]
B -- 否 --> D[问题不是自定义节点引起，参考其他排查文档]
B -- 否 --> D[问题不是自定义节点引起，参考其他<a href="/zh-CN/troubleshooting/overview">排查文档</a>]
C --> E{是否先排查前端扩展？}
E -- 是 --> F[在ComfyUI前端进行排查]
E -- 否 --> G[使用通用的二分法进行排查]
E -- 是 --> F[在<a href="#1-排查自定义节点的前端扩展">ComfyUI前端</a>进行排查<br/><li>仅需要重载前端</li>]
E -- 否 --> G[使用<a href="#2-通用的自定义节点排查方法">通用的二分法</a>进行排查<br/><li>需要多次重启 ComfyUI</li>]
F --> H[使用二分法定位有问题的节点]
G --> H
H --> I[修复、替换、报告或移除有问题的节点]
H --> I[<a href="#修复自定义节点问题">修复、替换、报告或移除有问题的节点</a>]
I --> J[问题解决]
```

## 如何确定是不是自定义节点导致的问题？
## 如何禁用所有的自定义节点？

如果禁用所有自定义节点后问题消失，那么我们可以定位这个问题是由自定义节点引起的。
<Tabs>
<Tab title="桌面版">
从设置菜单中启动禁用自定义节点的 ComfyUI 桌面版
![设置菜单-禁用自定义节点](/images/zh/troubleshooting/desktop-diable-custom-node.jpg)
或手动运行服务器：
```bash
cd path/to/your/comfyui
python main.py --disable-all-custom-nodes
```
</Tab>
<Tab title="手动安装">
```bash
cd ComfyUI
python main.py --disable-all-custom-nodes
```
</Tab>
<Tab title="便携版">
<Tabs>
<Tab title="修改 `.bat` 文件（推荐）">
打开便携版所在的文件夹，找到 `run_nvidia_gpu.bat` 或者 `run_cpu.bat` 文件
![修改 .bat 文件](/images/troubleshooting/Portable-disable-custom-nodes.jpg)
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 启动，并且自定义节点被禁用
</Tab>
<Tab title="通过命令行">
![ComfyUI troubleshooting](/images/troubleshooting/portable-disable-custom-nodes-cml-1.jpg)
1. 进入便携版所在的文件夹
2. 通过右键菜单 → 打开终端 来打开命令行

![ComfyUI troubleshooting](/images/troubleshooting/portable-disable-custom-nodes-cml-2.jpg)
3. 确保在命令行中文件夹名称是当前便携版所在的文件目录
4. 输入以下命令,来通过便携版的 python 来启动 ComfyUI 并禁用自定义节点
```
.\python_embeded\python.exe -s ComfyUI\main.py --disable-all-custom-nodes
```
</Tab>
</Tabs>
</Tab>
</Tabs>
**结果：**
- ✅ **问题消失**：自定义节点导致问题 → 继续步骤 2
- ❌ **问题仍然存在**：不是自定义节点问题 → [报告问题](#报告问题)

### 二分法排查思路

## 二分法

在本篇中我们将会介绍使用二分搜索来进行自定义节点问题排查的思路，也就是一次排查一半的自定义节点，直到定位到导致问题的自定义节点

Expand All @@ -50,7 +99,7 @@ flowchart TD
L --> M[结束]
```

## 根据不同的自定义节点问题类型使用不同的排查方法
## 两种排查方法

在本篇文档中，我们将排查的自定义节点分为两类

Expand All @@ -61,7 +110,7 @@ flowchart TD
首先让我们先了解不同类型的自定义节点可能导致的问题和原因

<Tabs>
<Tab title="包含前端扩展的自定义节点问题">
<Tab title="自定义节点前端扩展导致的问题">
对于自定义节点我们又特别需要对包含前端扩展的自定义节点进行优先排查，这类节点导致的问题是最多的, 他们主要的冲突是与 ComfyUI 前端版本更新产生的冲突。

常见的一些问题有:
Expand Down Expand Up @@ -100,7 +149,7 @@ flowchart TD

这两种上面两种不同的自定义节点问题里，自定义节点前端扩展和 ComfyUI 的冲突较为常见，我们会优先排查这类节点，后续的整体的问题排查思路如下

### 1.排查带有前端扩展的自定义节点
### 1.排查自定义节点的前端扩展

<Steps>
<Step title="禁用所有插件的前端扩展">
Expand All @@ -127,65 +176,6 @@ flowchart TD
### 2. 通用的自定义节点排查方法

<Steps>
<Step title="在禁用所有自定义节点的情况下运行 ComfyUI">
<Tabs>
<Tab title="桌面版">
从设置菜单中启动禁用自定义节点的 ComfyUI 桌面版

![设置菜单-禁用自定义节点](/images/zh/troubleshooting/desktop-diable-custom-node.jpg)

或手动运行服务器：

```bash
cd path/to/your/comfyui
python main.py --disable-all-custom-nodes
```
</Tab>
<Tab title="手动安装">
```bash
cd ComfyUI
python main.py --disable-all-custom-nodes
```
</Tab>
<Tab title="便携版">
<Tabs>
<Tab title="修改 `.bat` 文件（推荐）">

打开便携版所在的文件夹，找到 `run_nvidia_gpu.bat` 或者 `run_cpu.bat` 文件

![修改 .bat 文件](/images/troubleshooting/Portable-disable-custom-nodes.jpg)
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 启动，并且自定义节点被禁用
</Tab>
<Tab title="通过命令行">
![ComfyUI troubleshooting](/images/troubleshooting/portable-disable-custom-nodes-cml-1.jpg)
1. 进入便携版所在的文件夹
2. 通过右键菜单 → 打开终端 来打开命令行

![ComfyUI troubleshooting](/images/troubleshooting/portable-disable-custom-nodes-cml-2.jpg)

3. 确保在命令行中文件夹名称是当前便携版所在的文件目录
4. 输入以下命令,来通过便携版的 python 来启动 ComfyUI 并禁用自定义节点
```
.\python_embeded\python.exe -s ComfyUI\main.py --disable-all-custom-nodes
```
</Tab>
</Tabs>
</Tab>
</Tabs>

**结果：**
- ✅ **问题消失**：自定义节点导致问题 → 继续步骤 2
- ❌ **问题仍然存在**：不是自定义节点问题 → [报告问题](#报告问题)
</Step>
<Step title="使用二分搜索定位自定义节点">
对于二分搜索定位的方法，除了手动之外我们也有使用 comfy-cli 来进行自动化的二分搜索，具体方法如下：

Expand Down