troubleshooting

ComfyUI Troubleshooting Guide

Each section below is independent. Find the section whose symptom matches the error you are seeing and work through only those checks.

Connection Failures

Symptoms: Tools return connection errors, timeouts, or "ComfyUI not reachable" messages.

Checks:

1. Is ComfyUI running? Check the ComfyUI terminal/logs for errors.
2. Is the URL correct? Verify COMFYUI_URL environment variable or comfyui.url in ~/.comfyui-mcp/config.yaml. Default is http://localhost:8188.
3. Firewall/network: If ComfyUI runs on a remote machine, ensure port 8188 is accessible.
4. Use comfyui_get_system_info to test basic connectivity.

Model Not Found

Symptoms: comfyui_generate_image or workflows fail with "model not found" errors.

Checks:

1. Run comfyui_list_models with the correct folder type (e.g., "checkpoints", "loras") to see what's available.
2. Model filenames are case-sensitive and must include the extension (e.g., v1-5-pruned-emaonly.safetensors).
3. If the model isn't listed, it needs to be placed in the correct ComfyUI models directory.
4. If ComfyUI Model Manager is installed, use comfyui_search_models and comfyui_download_model to fetch models directly.
5. Run comfyui_list_model_folders to see all valid folder types.

Workflow Execution Failures

Symptoms: comfyui_run_workflow or comfyui_generate_image fails after submission.

Checks:

1. Run comfyui_validate_workflow first to catch structural issues.
2. Check for missing custom nodes — comfyui_list_nodes shows what's installed. If a workflow uses nodes that aren't installed, it will fail.
3. Check connections — a node output index must match what the node actually produces. Use comfyui_get_node_info to verify.
4. Check comfyui_get_queue to see if the job is stuck or if there's a queue backlog.
5. Check comfyui_get_progress with the prompt_id to see which node failed.

Queue Stuck / Job Not Completing

Symptoms: Jobs stay in "running" state indefinitely, or the queue doesn't process.