ComfyUIで生成が止まる・エラーが出る時の切り分け手順──公式トラブルシューティングを読む

ComfyUIでワークフローの途中にあるノードが赤くなったり、「Prompt execution failed」で生成が止まったりする状況は珍しくない。ComfyUI公式ドキュメントは、この種の不具合報告の大半が実はComfyUI本体ではなく「カスタムノード」に原因があると明記しており、切り分け方法を専用ページにまとめている。この記事は公式トラブルシューティングドキュメントの原文だけを根拠に、実際にやるべき手順を整理する。

• 不具合報告の大半はComfyUI本体でなくカスタムノードが原因、というのが公式の見立て。切り分けの起点はpython main.py --disable-all-custom-nodesで全カスタムノードを無効化して再現するかどうかを見ること
• モデル系のエラー（VAE不一致・CLIP設定ミス・ControlNetのアーキテクチャ不一致）は、公式の「Troubleshooting Model Issues」ページに具体的な症状・修正方法がまとめられている。たとえばFluxモデルにsdxl_vae.safetensorsを使うと形が崩れる、といった組み合わせミスが典型例
• Python 3.13が推奨バージョン。3.14は動くが一部のカスタムノードで問題が出うる、3.12はカスタムノードの依存関係で詰まった時のフォールバックとして案内されている——Pythonバージョンの選択自体がカスタムノード起因エラーの発生率に影響する

最初にやること：カスタムノードを疑う

ComfyUI公式のカスタムノードトラブルシューティングページは冒頭でこう述べている。

We receive a lot of feedback issues, and we find that most of the issues submitted are related to custom nodes. So please ensure that you have read the custom node troubleshooting guide before submitting an error report to ensure that the issue is not caused by ComfyUI core issues.

つまり「ノードが赤くなる」「生成が途中で止まる」といった不具合の多くは、ComfyUI本体のバグではなくインストール済みのカスタムノードが原因である可能性が高い、というのが公式の見立てだ。切り分けの起点は、全カスタムノードを無効化して同じ問題が起きるかを見ることになる。

無効化する方法は環境によって異なる。

• Desktop版：設定メニューからカスタムノードを無効化して起動
• 手動インストール・Portable版共通：python main.py --disable-all-custom-nodesを付けて起動

この状態で問題が再現しなければ「カスタムノードが原因」、再現すれば「ComfyUI本体側の問題」と切り分けられる。公式のフローチャートも、この分岐を最初のステップとして示している。

生成失敗時にまず見る場所

公式ドキュメントの「Common Issues & Quick Fixes」節は、「Prompt execution failed」というダイアログが出て生成が止まる状況について、次の順で確認するよう案内している。

1. 「Show report」をクリックして、実際のエラーメッセージを読む
2. カスタムノード起因かどうかを、上記の無効化手順で確認する
3. モデルファイルの配置が正しいか確認する
4. GPUメモリ（VRAM）を他のアプリが専有していないか確認する

「ノードが赤くなる」という見た目の変化だけを見て原因を推測するより、まずこの「Show report」の詳細メッセージを確認することが、公式が案内する最初の一手になる。

VRAM不足・低スペック環境向けの起動オプション

低VRAM環境や動作が極端に遅い場合、公式ドキュメントは起動時オプションによる調整を案内している。

# 低VRAMモード（テキストエンコーダをCPUで処理）
python main.py --lowvram

# CPUモード（非常に遅いが、どんなハードウェアでも動く。最後の手段としてのみ使用）
python main.py --cpu

パフォーマンス改善のためのオプションも複数案内されている。プレビュー生成を無効化する--preview-method none、最適化されたAttention機構を使う--use-pytorch-cross-attention、非同期の重みオフロードを行う--async-offloadなどだ。メモリ管理まわりでは、OS用に予約するVRAM量を指定する--reserve-vram <GB>や、キャッシュ戦略を切り替える--cache-none（低メモリ・低速）／--cache-lru <N>（N件キャッシュ・高速）といったオプションもある。

カスタムノード以外の原因：モデルの組み合わせミス

カスタムノードを疑っても直らない場合、公式ドキュメント「Troubleshooting Model Issues」は、もう1つの頻出原因として「チェックポイント・VAE・CLIP・ControlNetのアーキテクチャ不一致」を挙げている。SD1.5・SDXL・SD3・Fluxはそれぞれ内部のlatent空間・テキストエンコーダ構成が異なり、組み合わせを間違えると読み込みエラーやおかしな出力になる。

公式ドキュメントは簡易診断法も示している。VAEデコード段階でのエラーで「expected input[X, Y, Z] to have N channels, but got M channels」というメッセージが出た場合、チャンネル数(4ならSD系、16ならFlux系)を見ればどちらのモデル系列を想定しているかが分かる、としている。予防策としては「ワークフロー内のモデルは同じアーキテクチャファミリーで揃える」「同じ配布元(Hugging Faceの同一リポジトリなど)からモデル一式をまとめてダウンロードする」ことが案内されている。

モデルファイルが見つからない場合のエラー（Value not in list: ckpt_name: 'model-name.safetensors' not in []）については、ComfyUI Manager経由での自動ダウンロードに加えて、配置先のフォルダが公式ドキュメントで明記されている。

PythonバージョンとOSの組み合わせも見落としやすい

トラブルシューティング以前の話として、公式の「System Requirements」ページはPythonバージョンごとの安定性の違いを明記している。

対応OSはWindows・Linux・macOS(Apple Silicon)。Comfy Desktop版はWindows・macOS(Apple Silicon)向けにインストーラがあるが、Linux版は現時点で公式インストーラがなく、ソースからのビルドのみと明記されている。GPUの種類を問わず全システム対応させたい場合は、手動インストール(Manual Installation)がNVIDIA・AMD・Intel・Apple Silicon・Ascend NPU・Cambricon MLUをカバーする、とされている。

GPUベンダーごとのエラーパターン

公式ドキュメントは、GPUベンダーごとに典型的なエラーと対処を分けて記載している。

• NVIDIA：「Torch not compiled with CUDA enabled」が出る場合、torchを一度アンインストールしてCUDA対応版を入れ直す（pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130など）
• AMD：Linux限定でROCm対応のtorchが必要。RDNA2以前・RDNA3世代のカードではHSA_OVERRIDE_GFX_VERSION環境変数の指定が必要な場合がある
• Apple Silicon：MPSバックエンドの利用可否はpython -c "import torch; print(torch.backends.mps.is_available())"で確認。問題が出る場合は--cpuでの強制CPUモードにフォールバックできる
• Intel：「Torch not compiled with CUDA enabled」と出てもNVIDIA向けの対処をしてはいけない、と明記されている。Intel GPUはCUDAではなくXPUバックエンドを使うため、python -c "import torch; print('XPU available:', hasattr(torch, 'xpu') and torch.xpu.is_available())"で確認し、XPU対応版のtorchを別途入れる必要がある

Linux特有の「.soファイルが見つからない」エラー

Linux環境で頻出するのがLD_LIBRARY_PATH関連のエラーだ。公式ドキュメントが挙げる典型的な症状は次の3つ。

• libcuda.so.1: cannot open shared object file
• libnccl.so: cannot open shared object file
• ImportError: libnvinfer.so.X: cannot open shared object file

対処として、仮想環境のsite-packages内にあるNVIDIAライブラリのパスをLD_LIBRARY_PATHに追加する方法が案内されている。

export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib/python3.12/site-packages/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH

どのライブラリが不足しているかを特定するには、LD_DEBUG=libs python main.py 2>&1 | grep "looking for"でロード時のデバッグ出力を見る方法が案内されている。

バグ報告する前に用意すべき情報

公式ドキュメントは、GitHub Issuesに不具合を報告する際に含めるべき情報も具体的にリストしている——OS・ComfyUIバージョン・Pythonバージョン・PyTorchバージョン・GPUモデルとドライババージョン・インストール方法（Desktop／Portable／手動／comfy-cli）、加えて問題の再現手順・期待した挙動と実際の挙動・コンソールの完全なエラーテキスト・導入済みカスタムノードの一覧・問題を再現するワークフローファイル（.json）。報告先は問題の種類によって分かれており、ComfyUI本体は「GitHub Issues」（Comfy-Org/ComfyUI）、Desktopアプリの不具合は「Desktop GitHub Issues」（Comfy-Org/Comfy-Desktop）、フロントエンドの不具合は「Frontend GitHub Issues」（Comfy-Org/ComfyUI_frontend）とそれぞれ別のGitHubリポジトリが案内されている。一方カスタムノードの不具合だけはGitHubリポジトリでの一元的な報告先を持たず、「Contact the specific custom node developer」（該当カスタムノードの開発者に直接連絡する）よう案内されている。

ノードが赤く表示される仕組み自体の説明は見つからなかった

限界を先に書く。

「ノードが赤くなる」という表示色そのものの技術的な意味。 公式トラブルシューティングページは症状ベースの対処法を中心に構成されており、UI上でノードが赤く表示される仕組み自体についての専用の説明は、今回確認した範囲では見つからなかった。

個別のカスタムノードごとの既知の不具合。 カスタムノードは開発元がそれぞれ異なるため、特定のカスタムノードで頻発する不具合の一覧は、本記事の範囲（ComfyUI公式ドキュメント）には含まれておらず確認していない。

Windows版のインストーラ不具合の網羅的な一覧。 「Installation fails」「Maintenance page」など代表的な症状は確認できたが、Windows環境特有の不具合を網羅的には確認していない。

モデルの組み合わせミス以外の、生成品質そのものに関わる不具合。 「Troubleshooting Model Issues」ページで確認できたのはあくまでエラーで止まる・読み込めないケースの切り分けで、正常に動いているように見えて出力品質が想定と違う、といった診断の難しいケースまでは扱っていない。

関連記事

• ローカルで動かすStable Diffusionの導入手順【2026年版】
• ローカルLLMとは何か──自分のPCでAIを動かす仕組み・利点・始め方を解説
• AI画像アップスケーリングツール比較【2026年版】