comfyui-mcp/plugin/commands/debug.md

Local-first, agent-native control plane for ComfyUI — MCP server + autonomous sidebar agent that drives your live graph in natural language on ANY LLM: Claude/ChatGPT/Gemini on your subscription (no API key), free local models via Ollama (fully offline),

---
description: Diagnose why a ComfyUI workflow failed
argument-hint: prompt_id or "last" to debug the most recent execution
---

# /comfy-debug — Diagnose a Failed Workflow

The user wants to find out why a ComfyUI workflow execution failed and get a suggested fix.

## Instructions

1. **Get the execution history.** The argument is: $ARGUMENTS
   - If a prompt_id is provided, call `get_history(action="list")` with that prompt_id
   - If "last" is provided or no argument given, call `get_history(action="list")` with no prompt_id to get the most recent execution

2. **Extract the error.** From the history response, identify:
   - `node_id`: the node where execution failed
   - `node_type` / `class_type`: what kind of node it was
   - `exception_message`: the error message
   - `traceback`: the full Python traceback

   If the execution succeeded (no error), tell the user it completed normally and show the output summary.

3. **Get relevant logs.** Call `get_system_stats (action:"logs")` with a `keyword` filter matching the error. Use the exception class name (e.g., "RuntimeError", "ValueError") or a distinctive phrase from the error message. Request up to 200 lines.

4. **Inspect the failing node.** Call `create_workflow (action:"node_info")` with the `node_type` of the failing node. Check:
   - What inputs does the node expect?
   - Are there required inputs that might be missing or mistyped?
   - What data types are expected for each input?

5. **Check for missing models.** If the error mentions a missing file, model, or checkpoint:
   - Call `list_local_models` to see what's installed
   - Compare against what the workflow references
   - If a model is missing, suggest using `download_model` `action:"download"` or provide a search query for `action:"search"`

6. **Check for missing nodes.** If the error is a `KeyError` or mentions an unknown node type:
   - The node pack may not be installed
   - Call `search_custom_nodes` (`action: "search"`) with the node class name as `query` to find which pack provides it
   - Suggest installing the pack

7. **Present the diagnosis.** Provide a summary:
   - **What failed**: node type, node ID, and a one-line description
   - **Why it failed**: root cause explanation in plain language
   - **Suggested fix**: concrete steps the user can take to resolve the issue
   - **Traceback excerpt**: the most relevant lines from the traceback (not the full dump)

## Common Failure Patterns

- **OOM / CUDA out of memory**: Suggest reducing resolution, using FP8 models, or `clear_vram` before retrying
- **Missing checkpoint/model file**: Show what's installed, offer to download the right one
- **Missing custom node**: Identify the pack and suggest installation
- **Shape mismatch**: Usually a resolution or latent size issue; check that width/height are multiples of 8 (or 64 for some models)
- **NaN/Inf in tensor**: Model corruption or extreme CFG values; suggest re-downloading the model or lowering CFG
- **Connection type mismatch**: A node is receiving the wrong data type; check the workflow wiring

## Example

User: `/comfy-debug last`

Steps:
- Call `get_history(action="list")` with no prompt_id
- Find error: node 12 (KSampler) threw RuntimeError "Expected all tensors to be on the same device"
- Call `get_system_stats (action:"logs")` with keyword "RuntimeError"
- Call `create_workflow (action:"node_info")` for "KSampler"
- Diagnose: model and conditioning are on different devices, likely a VRAM issue
- Suggest: restart ComfyUI or use `clear_vram` before retrying

## Notes

- If multiple nodes errored, focus on the first failure in the execution chain; downstream errors usually cascade from it
- The traceback is Python-level; translate it into plain language for the user
- If the error is ambiguous, suggest the user share their workflow JSON for a closer look