Skip to content

Commit 54055e7

Browse files
[docs] Centralize troubleshooting documentation (#4040)
1 parent 69f33f3 commit 54055e7

File tree

1 file changed

+4
-96
lines changed

1 file changed

+4
-96
lines changed

README.md

Lines changed: 4 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -703,100 +703,8 @@ See [locales/README.md](src/locales/README.md) for details.
703703

704704
## Troubleshooting
705705

706-
> **Note**: For comprehensive troubleshooting and how-to guides, please refer to our [official documentation](https://docs.comfy.org/). This section covers only the most common issues related to frontend development.
706+
For comprehensive troubleshooting and technical support, please refer to our official documentation:
707707

708-
> **Desktop Users**: For issues specific to the desktop application, please refer to the [ComfyUI desktop repository](https://github.com/Comfy-Org/desktop).
709-
710-
### Debugging Custom Node (Extension) Issues
711-
712-
If you're experiencing crashes, errors, or unexpected behavior with ComfyUI, it's often caused by custom nodes (extensions). Follow these steps to identify and resolve the issues:
713-
714-
#### Step 1: Verify if custom nodes are causing the problem
715-
716-
Run ComfyUI with the `--disable-all-custom-nodes` flag:
717-
718-
```bash
719-
python main.py --disable-all-custom-nodes
720-
```
721-
722-
If the issue disappears, a custom node is the culprit. Proceed to the next step.
723-
724-
#### Step 2: Identify the problematic custom node using binary search
725-
726-
Rather than disabling nodes one by one, use this more efficient approach:
727-
728-
1. Temporarily move half of your custom nodes out of the `custom_nodes` directory
729-
```bash
730-
# Create a temporary directory
731-
# Linux/Mac
732-
mkdir ~/custom_nodes_disabled
733-
734-
# Windows
735-
mkdir %USERPROFILE%\custom_nodes_disabled
736-
737-
# Move half of your custom nodes (assuming you have node1 through node8)
738-
# Linux/Mac
739-
mv custom_nodes/node1 custom_nodes/node2 custom_nodes/node3 custom_nodes/node4 ~/custom_nodes_disabled/
740-
741-
# Windows
742-
move custom_nodes\node1 custom_nodes\node2 custom_nodes\node3 custom_nodes\node4 %USERPROFILE%\custom_nodes_disabled\
743-
```
744-
745-
2. Run ComfyUI again
746-
- If the issue persists: The problem is in nodes 5-8 (the remaining half)
747-
- If the issue disappears: The problem is in nodes 1-4 (the moved half)
748-
749-
3. Let's assume the issue disappeared, so the problem is in nodes 1-4. Move half of these for the next test:
750-
```bash
751-
# Move nodes 3-4 back to custom_nodes
752-
# Linux/Mac
753-
mv ~/custom_nodes_disabled/node3 ~/custom_nodes_disabled/node4 custom_nodes/
754-
755-
# Windows
756-
move %USERPROFILE%\custom_nodes_disabled\node3 %USERPROFILE%\custom_nodes_disabled\node4 custom_nodes\
757-
```
758-
759-
4. Run ComfyUI again
760-
- If the issue reappears: The problem is in nodes 3-4
761-
- If issue still gone: The problem is in nodes 1-2
762-
763-
5. Let's assume the issue reappeared, so the problem is in nodes 3-4. Test each one:
764-
```bash
765-
# Move node 3 back to disabled
766-
# Linux/Mac
767-
mv custom_nodes/node3 ~/custom_nodes_disabled/
768-
769-
# Windows
770-
move custom_nodes\node3 %USERPROFILE%\custom_nodes_disabled\
771-
```
772-
773-
6. Run ComfyUI again
774-
- If the issue disappears: node3 is the problem
775-
- If issue persists: node4 is the problem
776-
777-
7. Repeat until you identify the specific problematic node
778-
779-
#### Step 3: Update or replace the problematic node
780-
781-
Once identified:
782-
1. Check for updates to the problematic custom node
783-
2. Consider alternatives with similar functionality
784-
3. Report the issue to the custom node developer with specific details
785-
786-
### Common Issues and Solutions
787-
788-
- **"Module not found" errors**: Usually indicates missing Python dependencies. Check the custom node's `requirements.txt` file for required packages and install them:
789-
```bash
790-
pip install -r custom_nodes/problematic_node/requirements.txt
791-
```
792-
793-
- **Frontend or Templates Package Not Updated**: After updating ComfyUI via Git, ensure you update the frontend dependencies:
794-
```bash
795-
pip install -r requirements.txt
796-
```
797-
798-
- **Can't Find Custom Node**: Make sure to disable node validation in ComfyUI settings.
799-
800-
- **Error Toast About Workflow Failing Validation**: Report the issue to the ComfyUI team. As a temporary workaround, disable workflow validation in settings.
801-
802-
- **Login Issues When Not on Localhost**: Normal login is only available when accessing from localhost. If you're running ComfyUI via LAN, another domain, or headless, you can use our API key feature to authenticate. The API key lets you log in normally through the UI. Generate an API key at [platform.comfy.org/login](https://platform.comfy.org/login) and use it in the API Key field in the login dialog or with the `--api-key` command line argument. Refer to our [API Key Integration Guide](https://docs.comfy.org/essentials/comfyui-server/api-key-integration#integration-of-api-key-to-use-comfyui-api-nodes) for complete setup instructions.
708+
- **[General Troubleshooting Guide](https://docs.comfy.org/troubleshooting/overview)** - Common issues, performance optimization, and reporting bugs
709+
- **[Custom Node Issues](https://docs.comfy.org/troubleshooting/custom-node-issues)** - Debugging custom node problems and conflicts
710+
- **[Desktop Installation Guide](https://docs.comfy.org/installation/desktop/windows)** - Desktop-specific installation and troubleshooting

0 commit comments

Comments
 (0)