How to Repair a Broken ComfyUI Workflow with Claude

Do not ask Claude to rewrite the whole workflow first. Preserve the original save-format JSON and the exact errors, prove that a current default workflow runs with custom nodes disabled, and then let Claude classify only the evidence you provide. Change one dependency at a time, rebuild the smallest viable graph, run one image, and personally verify that the result appears in Save Image and can be saved and reopened.

This process turns a vague “ComfyUI changed” problem into four testable layers: ComfyUI core, frontend extensions, custom nodes, model files, or the old graph itself. The official ComfyUI troubleshooting guide likewise recommends testing the default workflow, disabling custom nodes, and reading the exact terminal error before filing or applying a fix.

The repair sequence at a glance

1. Keep the original workflow in normal save format and never overwrite it.
2. Capture the full error, startup log, install type, versions, and recent changes.
3. Disable all custom nodes and run the current default image workflow.
4. Give Claude a bounded evidence packet; analysis comes before edits or installs.
5. Classify the fault as core, frontend, custom node, model, or unknown.
6. Update or replace one incompatible node, or rebuild a minimal current graph.
7. Run one small image and verify the actual saved file.

1. Freeze the workflow and evidence before changing anything

Save the old workflow as ordinary JSON, then make a separate working copy. A small case directory keeps the investigation reproducible:

comfyui-repair-case/
  workflow-original.json
  workflow-working.json
  error-report.txt
  startup-log.txt
  environment.md

Treat workflow-original.json as read-only. Put the complete text from Show report in error-report.txt, not a paraphrase such as “the node is broken.” Save import failures, dependency conflicts, and tracebacks from the launch terminal in startup-log.txt. In environment.md, record whether this is Desktop, Portable, or a manual install; the ComfyUI version; operating system; GPU; and whether core, frontend, custom nodes, or models were recently updated.

Also preserve the distinction between save format and API format. The official Workflow API Format page explains that a normal saved workflow retains positions, colors, groups, and other editing metadata, while API format is a leaner representation for programmatic submission. Keep the normal save-format original for repair work. Export a separate API copy only when an API is actually part of the task.

2. Prove a clean ComfyUI baseline before touching the old graph

The old workflow should not be your first test. Temporarily disable third-party nodes. Desktop users can use the settings control; a manual install can normally be started with:

python main.py --disable-all-custom-nodes

Load the current default Image Generation template, select a compatible checkpoint that is already visible in the model dropdown, and run one image. The official custom-node troubleshooting guide gives a useful split: if the issue disappears with custom nodes disabled, a custom node is involved; if it persists, investigate core, frontend, models, or the environment.

Use the result to choose the next branch:

Baseline result	More likely layer	Next proof
The default workflow cannot open or run	Core install, frontend, model, or hardware	Fix the baseline before editing the old graph
The default works, but the old graph reports missing nodes	Missing, renamed, or unloaded custom nodes	Map node types from the JSON to their owners
The old graph loads, then fails at one node	Model architecture, connections, dependencies, or memory	Preserve the first failing node and full report
Disabling frontend extensions restores the UI	Incompatible third-party frontend extension	Re-enable extensions by halves to isolate one

If the default graph fails, a rewritten old JSON cannot prove a successful repair.

3. Give Claude a bounded evidence packet

Anthropic describes Claude Code as able to read a codebase, edit files, and run commands. Those capabilities are useful, but they also mean the first pass should be analysis-only. Start Claude in the case directory above, or attach the same files in a chat, and use a constraint like this:

You are diagnosing a ComfyUI workflow that stopped working after an update.

Read only:
- workflow-original.json
- workflow-working.json
- error-report.txt
- startup-log.txt
- environment.md

Do not install, update, delete, rename, or edit anything yet.
First:
1. Inventory node types and referenced model files.
2. Classify each problem as ComfyUI core, frontend extension,
   custom node, model file, or unknown.
3. Quote the exact JSON field or error line behind every conclusion.
4. Propose the smallest reversible change.
5. Wait for approval before editing workflow-working.json.

Do not claim the repair succeeded until I run one image and confirm a saved file.

A useful answer is a mapping table: old node type, owning extension, input/output contract, possible replacement, parameter mapping, evidence, and risk. If the owner or replacement cannot be established, Claude should mark it unknown rather than infer a package from a similar name.

4. Classify the failure instead of updating everything

Missing node: identify its owner before replacing it

Inspect the missing node’s type, title, and links in the normal save JSON. Similar names do not guarantee compatible sockets or widget values, so changing a string in JSON is not a safe migration. Determine whether the node belongs to ComfyUI core or a specific custom-node repository, then compare the old and new inputs, outputs, and parameters.

If the extension is maintained, update only that extension and retest. If it is abandoned, choose a maintained alternative or rebuild that small function with core nodes. The official guide presents the same choices: update, replace, report the problem to the author, or remove/disable the node.

Frontend-extension conflict: disable, then bisect

Some custom nodes also inject frontend extensions. A blank UI, broken links, missing previews, or failed frontend/backend communication after an update can come from this layer. Disable third-party frontend extensions first. If the symptom disappears, enable half at a time and repeat. This binary-search method retains causality and is safer than reinstalling everything.

Missing model: inspect folders and search paths

An old graph may reference a checkpoint, VAE, LoRA, or ControlNet that was removed, renamed, or moved. ComfyUI discovers models under the categorized ComfyUI/models/ folders and paths configured in extra_model_paths.yaml. If a selector is empty or shows null, verify the real location, then refresh or restart ComfyUI. Do not rename an incompatible model merely to satisfy an old filename.

Architecture mismatch: inspect the family, not just the file name

The official model troubleshooting guide advises keeping workflow models within the same architecture family. Mixing a checkpoint, VAE, text encoder, or ControlNet from different families can surface as tensor-shape errors during sampling or VAE decode. Claude can correlate the stack trace with the graph, but an official template for the intended model family is the better compatibility baseline.

5. Update or replace one node in the working copy

Before approving an edit, ask Claude to provide this change plan:

Item	Question that must be answered
Old node	What is the exact JSON type?
Owner	Is it core, a custom node, or a frontend extension?
Replacement	Do the input and output types match?
Parameter migration	Which widget values can stay, and which need rebuilding?
Rollback	How will the previous workflow-working.json be restored?

Approve changes only to workflow-working.json, one fault at a time. Reload after each edit and confirm that the node is present, connections remain valid, and parameters have not shifted before making the next change. A bulk “update all custom nodes” can create a second compatibility problem and destroys the evidence needed to know which change mattered.

Community pages can help match symptoms, but they are not universal diagnoses. For example, frontend issue #6328 and ComfyUI discussion #14344 are individual user reports. Use them only when the version, error, and node context match your case.

6. Rebuild a minimal, current image spine

If the old graph contains many obsolete LoRA, ControlNet, upscaling, preview, and utility branches, repairing every branch at once is riskier than rebuilding the core. Rebuild it from ComfyUI’s official minimal Save-format example. This is a branched graph, not a serial pipeline: several outputs converge on KSampler, and VAEDecode separately receives the checkpoint’s VAE.

Output port	Input port
CheckpointLoaderSimple.MODEL	KSampler.model
CheckpointLoaderSimple.CLIP	positive-prompt CLIPTextEncode.clip
CheckpointLoaderSimple.CLIP	negative-prompt CLIPTextEncode.clip
positive-prompt CLIPTextEncode.CONDITIONING	KSampler.positive
negative-prompt CLIPTextEncode.CONDITIONING	KSampler.negative
EmptyLatentImage.LATENT	KSampler.latent_image
KSampler.LATENT	VAEDecode.samples
CheckpointLoaderSimple.VAE	VAEDecode.vae
VAEDecode.IMAGE	SaveImage.images

EmptyLatentImage does not receive conditioning. KSampler needs four independent inputs—model, positive, negative, and latent_image—while VAEDecode needs both the sampled samples and the checkpoint’s vae. Once those ports are connected as shown, the minimal graph can actually be queued and save an image.

Use this wiring only when the selected checkpoint architecture matches the official example. A newer model may require a different loader, text encoder, latent node, or VAE path; in that case, follow that model’s official workflow instead of forcing this graph. For the baseline, choose a compatible checkpoint already visible in Load Checkpoint, set batch size to 1, use a modest resolution, and leave the old optional branches disconnected. Once the spine passes, add one LoRA, ControlNet, upscaler, or custom post-processing branch and run again after each addition.

The goal is not to make the new graph look like the old one. It is to establish a provably working current spine, then migrate only the capabilities the old workflow actually needs. Claude can compare the two JSON files and prepare a migration map, but execution remains the acceptance test.

7. Run one small image and verify the saved output

A workflow that merely opens is not repaired. Complete the loop using the official first-generation guide:

1. After installing or moving models, press R to refresh model lists, or restart if needed.
2. Confirm that Load Checkpoint shows a visible, compatible model.
3. Click Run or press Ctrl + Enter.
4. Wait for the queue to finish with no missing-node, validation, or red-node failure.
5. Confirm that the image appears in Save Image.
6. Right-click to save it locally, record the filename, and reopen it in an image viewer.
7. Optionally drag the generated ComfyUI PNG back into the interface to confirm its embedded workflow metadata can be read.
8. Save the repaired normal-format graph as workflow-repaired.json; keep workflow-original.json unchanged.

Your acceptance record should include the repaired workflow filename, output image filename, model used, enabled custom nodes, node replacements, and any known limitations. Only then is “fixed” an evidence-based status.

What to do when a branch still fails

• The default workflow fails with custom nodes disabled: stop editing the old graph and repair the installation, model, driver, or frontend baseline.
• The default works but the old graph still has missing nodes: continue ownership and replacement mapping; do not guess by renaming JSON types.
• The graph loads but generation fails: start from the first failing node in Show report; check model family and links before treating it as a memory problem.
• Failure returns when one group of extensions is enabled: keep bisecting until one custom node or frontend extension remains.
• The original node is unmaintained: replace or rebuild that function; document any behavioral difference rather than hiding it.
• Claude provides no quoted error or JSON evidence: treat the suggestion as a hypothesis and do not execute it yet.

Final takeaway

Claude is most reliable here as an evidence organizer and change planner, not as an unverified auto-repair button. The dependable loop is backup → clean baseline → classify → smallest change → one image → saved-file verification. Keep the original graph, change one variable at a time, and let actual ComfyUI output—not a confident explanation—decide whether the workflow is repaired.