ComfyUIのエラー解決：赤いノード、VAE異常、更新後のロールバック

共有されたworkflowを開くと、赤いunknown nodeが一列に並んでいます。ManagerのInstall Missing Custom Nodesを実行して再起動しても、赤いままです。Managerは万能な修復ツールではありません。ノードコードは管理できますが、すべての依存関係が正しく入る保証はなく、モデルファイルもインストールしません。

赤いノードはComfyUIトラブルシュートの入口の一つにすぎません。loadingで停止する、UIが真っ白になる、更新前まで動いていたworkflowが壊れる、VAE出力が灰色や黒になる、コピーしたモデルがdropdownに出ない、といった症状もあります。原因はcustom nodeの競合、依存関係のバージョン、モデルパス、精度フラグ、VRAMピークに分かれます。

症状から始めるのが最短です。目の前の状態を一致させ、原因になりそうな層を決め、影響の小さいテストから進めます。

症状別クイックリファレンス

次の表は、よくある六つの入口をまとめています。最初の列で症状を選び、二列目で原因の範囲を決め、三列目の操作から始めてください。

症状	最も可能性の高い原因	最初に行うこと
赤いノード / unknown nodes	custom node不足、ノード改名、ノードのimport失敗	ManagerまたはRegistryでノード名を検索し、コンソールのImport failedを確認する
loadingで停止 / 白画面 / blank screen	custom nodeのfrontend extension競合	python main.py --disable-all-custom-nodesで起動テストする
Queue後にPrompt execution failed	custom nodeエラー、モデル問題、VRAM不足	Show reportを開き、どの処理で失敗したか確認する
VAE出力が灰色 / 白 / 色ずれ / 黒	VAEの組み合わせまたは精度設定	VAE loaderの接続、ファイルの組み合わせ、--fp16-vaeを確認する
更新後にworkflowが壊れた	coreとcustom nodeのバージョン不一致、依存関係競合	更新した範囲を特定し、update内のスクリプトを確認する
モデルを置いてもdropdownに出ない	モデルパスの誤り、ノード定義が未更新	対応するComfyUI/models/サブフォルダーを確認し、再起動または更新する

最初からインストール先を削除しないでください。workflow、ログ、ノード一覧、バージョンを保存してから環境を変更します。

赤いノードの切り分け：custom nodeかモデルか

赤いunknown nodeは通常、ComfyUIがそのノード型を見つけられないことを意味します。custom nodeの不足、改名、無効化、依存関係importの失敗が考えられます。モデル不足は、loaderのdropdownにファイルが出ないか、実行時のモデルエラーとして現れることが多いため、別の故障として扱います。

1. ManagerのInstall Missingで解決できる範囲

ComfyUI-ManagerのInstall Missing Custom Nodesが主に解決するのは、ノードコードの不足です。Registryやソースリポジトリからノードを導入しますが、次の項目は別の対応が必要になる場合があります。

• requirements.txtに記載されたtorch、numpy、xformersなどのPython依存関係
• checkpoint、VAE、LoRA、ControlNetなどのモデルファイル
• custom node固有のモデルパス

Comfy DesktopにはManagerが含まれ、既定で有効です。現在のPortableとManualでは、新しいManagerがComfyUI coreに組み込まれていますが、manager_requirements.txtをインストールし、--enable-managerで起動する必要があります。Managerにノードが出ない場合は、Registry未登録か、通信障害によりキャッシュまたはローカル情報だけが表示されている可能性があります。似た名前のパッケージを入れる前に、元リポジトリを確認してください。

確認順序は、コンソールのImport failed → ManagerまたはRegistryのノード名 → モデルパスです。workflowのimportから再現までの手順は、ComfyUIワークフロー再利用ガイドを参照してください。

2. Import failedの読み方

コンソールにImport failedが出たら、tracebackの最後の部分にあるmissing moduleや競合バージョンを確認します。エラー種別で次の操作を決めます。

判断手順：

1. ModuleNotFoundError: No module named 'xxx' → Python package不足

   • system Pythonではなく、ComfyUIが使うPython環境にインストールします
   • Portableのコマンド：python_embeded\python.exe -m pip install -r custom_nodes\xxx\requirements.txt
   • DesktopとManualではパスが異なるため、ComfyUIが実際に使うPythonを特定します

2. torch / CUDA / cuDNN関連エラー → PyTorchとGPU backendの不一致

   • PyTorchを確認：python -c "import torch; print(torch.__version__)"
   • GPU driverが現在のsystem requirementsを満たすか確認します
   • ノードが要求するtorchと、ComfyUI環境のtorchが競合する場合があります

3. custom node内部の例外 → ノードのリリース問題またはコード不具合

   • ノードのGitHub issuesで同じtracebackを検索します
   • 新しいリリースで発生した場合は、既知の正常なcommitを試します

変わりやすい情報：パッケージ化時点でComfyUIはPython 3.13を推奨し、3.13で一部custom nodeの依存関係に問題がある場合は3.12をfallbackとしています。PyTorchとCUDAの条件は変化が速いため、現在のsystem requirementsを確認してください。

3. Managerでインストール済みなのに不足する場合

Managerでインストール済みと表示されても、再起動後に赤いまま、またはtorchとtorchvisionの競合が出る場合があります。インストール表示だけでは読み込み成功を判断できません。

インストール済みノードが使えない理由：

• 通信障害でリポジトリまたは依存関係の取得が完了していない
• ノードのPython requirementsがComfyUI環境に入っていない
• ノードが無効、またはimport自体に失敗している
• ノードのバージョンが現在のComfyUIと互換性を持たない

依存関係が競合する理由：

• 複数のcustom nodeがtorch、torchvision、numpyの異なるバージョンを要求する
• requirements.txtの厳密な固定が既存packageと競合する

解決順序：

1. tracebackの最後まで読み、Import failedの節に沿って分類します
2. 競合ノードを無効化または削除し、ComfyUIが回復するか確認します
3. requirements.txtにtorch==2.4.1のような厳密な固定がないか調べます
4. 解決しない場合は、次を添えてissueを作成します
   • 完全なtraceback
   • python main.py --disable-all-custom-nodesの結果
   • Python、PyTorch、GPU driverのバージョン

変わりやすい情報：Managerは新UI、core組み込み、legacy UIが併存しています。表示名やメニュー位置は現在の公式ドキュメントを参照してください。実際の原因がOOMやVRAMピークなら、ComfyUIの低VRAM・高速化実践に進みます。

4. モデルパスとdropdownに出ない問題

ComfyUIにはモデルweightが同梱されません。checkpoint、VAE、LoRA、ControlNet、upscalerは別にダウンロードし、対応するComfyUI/models/サブフォルダーに配置します。

ファイルが出ない場合の確認順序：

1. 正しいディレクトリ

   • checkpointはComfyUI/models/checkpoints/
   • VAEはComfyUI/models/vae/
   • LoRA、ControlNet、upscalerはそれぞれのtypeディレクトリ
   • custom nodeが別パスを使う場合は、そのプロジェクトのREADMEに従います

2. 再起動または更新

   • ComfyUIを再起動するか、現在のUIが対応するノード定義の更新方法を使います

3. ファイルの完全性

   • ダウンロード元のファイルサイズと比較します
   • 不完全なら再ダウンロードまたは検証します

4. 対応するloader

   • モデルtypeに対応したloaderとworkflow templateを選びます
   • FLUX、SD3.xなどの新しい構成では、特定のtext encoder、VAE、ノード組み合わせが必要な場合があります
   • custom nodeのモデルパスは、一般的なComfyUI/models/の説明と異なることがあります

5. extra_model_paths.yaml

   • PortableとManualはextra_model_paths.yamlで外部モデルライブラリを参照できます。保存後は再起動します
   • Desktopは専用のextra models configを使うため、現在の公式パスを確認します

モデルとVAEの組み合わせは、Stable Diffusionモデル選定ガイドを参照してください。

—disable-all-custom-nodesでloading停止を診断する

ComfyUIがloadingで止まる、白画面になる、UIを描画できない場合、custom nodeのfrontend extensionが原因のことがあります。--disable-all-custom-nodesを使うと、custom nodeが関係するかすぐに判定できます。

1. custom nodeなしで起動する

コマンド：

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

Windows Portable：

run_nvidia_gpu.batまたはrun_cpu.batをコピーし、起動コマンドに--disable-all-custom-nodesを追加して、safe-start用に別名保存します。

結果の判断：

• custom node無効で問題が消える → custom nodeが原因
  • 二分探索を続けます
• 問題が残る → custom node以外が原因
  • ComfyUI core、system requirements、GPU driver、Python / PyTorchを確認します
  • モデルファイルとパスを確認します
  • ComfyUIの低VRAM・高速化実践でVRAMピークを確認します

変わりやすい情報：現在の起動フラグはpython main.py --helpで確認してください。

2. 二分探索で問題ノードを特定する

safe-startテストでcustom nodeが原因だと分かったら、推測ではなく二分探索で候補を減らします。

原理：custom nodeを半分ずつ移動または有効化し、結果を見ながら疑わしい集合を半分にしていきます。

手順：

1. ComfyUI/custom_nodes/をバックアップします
2. ノードフォルダーの半分を一時テストディレクトリに移します
3. ComfyUIを起動し、問題を再現します
4. 結果を判断します
   • 問題が消える → 原因ノードは移動した半分にあります
   • 問題が残る → 原因ノードは残した半分にあります
5. 一つのノード、または小さな組み合わせになるまで繰り返します

ノード特定後：

• GitHub issuesで同じtracebackを検索します
• requirements.txtの厳密なversion固定を確認します
• ノードを更新、置換、無効化、削除します
• 新しいリリースが原因なら、以前の正常なcommitを試します

issueに含める情報：

• ComfyUIのバージョン
• 完全なエラーと再現手順
• OS
• --disable-all-custom-nodesテストの結果
• Python、PyTorch、GPU driver、hardware情報

VAEの灰色・黒画像・組み合わせ不一致を調べる

灰色、白、色ずれ、黒画像は、VAEの不一致、decode接続の誤り、VAE精度、attention精度、新しいモデルに必要なファイルやノードの不足で起こります。この順序で確認します。

1. VAEトラブルシュートの順序

手順：

1. VAEの接続を確認する

   • checkpoint loaderが出力するVAE、または別のVAE loaderをdecode nodeに接続します
   • VAEを内蔵するcheckpointもあれば、別ファイルが必要なモデルもあります

2. VAEをモデルとworkflowに合わせる

   • SD1.5、SDXL、FLUX、SD3.xでは、VAE、text encoder、loaderの組み合わせが異なる場合があります
   • まず最小の公式workflow template、またはモデルプロジェクトのREADME例を実行します

3. --fp16-vaeを確認する

   • 公式Startup Flagsには、--fp16-vaeがblack imagesを起こす可能性があると記載されています
   • 外すか、hardwareが対応する場合は--fp32-vae / --bf16-vaeを試します

4. 精度フラグを試す

   • --fp32-vae：full precisionのVAE。通常はVRAM使用量が増えます
   • --bf16-vae：BF16のVAE。対応hardwareとbackendが必要です
   • --cpu-vae：VAEをCPUで実行します。通常は遅くなります
   • --force-upcast-attention：attention upcastで黒画像が直るかを確認するフラグで、一般的な画質向上設定ではありません

5. 最後にVRAM、driver、依存関係を調べる

   • VRAMピークでVAE decodeが失敗する場合があります
   • GPU driverが現在の条件を満たすか確認します
   • PyTorchとGPU backendが一致するか確認します

よくある症状：

症状	考えられる原因
灰色 / 白 / 色ずれ	VAE不一致、decode経路の誤り、workflowとモデルの不一致
完全な黒画像	--fp16-vae、attention精度、VRAMピーク、無効なモデル組み合わせ
読み込みエラー	VAE破損、パス誤り、必要ファイルの不足

2. fp16 VAEの黒画像リスク

--fp16-vaeでリソース使用量を抑える手順は多くありますが、公式Startup Flagsはblack imagesの可能性を明記しています。モデル、hardware、ログを確認せずに適用しないでください。

VAE精度フラグ：

フラグ	効果	検討する場面
--fp16-vae	VAEをFP16で実行し、通常はリソース使用量を抑える	黒画像になる可能性があるため慎重に使う
--fp32-vae	VAEをfull precisionで実行する	黒画像の切り分けで試せるが、通常はVRAM使用量が増える
--bf16-vae	VAEをBF16で実行する	対応hardwareとbackendが必要
--cpu-vae	VAEをCPUで実行する	VRAMが厳しい場合のテスト手段。通常は遅い

Attention精度：

• --force-upcast-attention：attention upcastで黒画像が直るか検証します
• --dont-upcast-attention：前のフラグと同時使用できず、debug用途です

実行順序：

• チュートリアルの「高速化フラグ」をそのままコピーせず、症状とコンソール出力を先に読みます
• 黒画像では最初に--fp16-vaeを外し、環境に応じて--fp32-vaeまたは--force-upcast-attentionを試します
• フラグ名と既定値は現在のpython main.py --helpで確認します
• OOMと低VRAMの詳細は、ComfyUIの低VRAM・高速化実践を参照してください

3. VAEとモデルの不一致を切り分ける

モデルまたはVAEを変えた後に、動いていたworkflowの出力が崩れた場合は、モデル、VAE、loader、templateの不一致を疑います。モデルfamilyごとに必要なファイルとノードの組み合わせが異なります。

モデルfamily別の確認項目：

モデルfamily	VAEの確認	loader / workflowの確認
SD1.5 checkpoint	内蔵VAEまたは対応するSD1.5 VAEを使う	SD1.5対応の基本workflowから始める
SDXL checkpoint	内蔵VAEまたは対応するSDXL VAEを使う	SDXL対応templateとloaderを使う
FLUX / SD3.x	モデルREADMEに従ってVAEとtext encoderを用意する	公式templateまたはproject文書に従う

診断手順：

1. モデルREADME、project page、公式templateを確認します
   • VAE内蔵の有無、必要なcompanion weights、loaderを確認します
2. 各loaderで選択したファイルを確認します
   • dropdownのVAEがモデルとworkflowに合うか確認します
3. 最小の公式templateで再現します
   • custom post-processingを外し、ノードを一つずつ戻します

症状の対応：

症状	主な原因
灰色 / 白 / 色ずれ	VAE、モデル、decode経路の不一致
読み込みエラー	VAE破損、パス誤り、必要ファイルの不足
最小workflowは動くが元workflowは動かない	post-processingまたはcustom nodeがdecode経路を変えている

モデルとVAEの詳細は、Stable Diffusionモデル選定ガイドを参照してください。

更新方針：stable、development、バックアップ、ロールバック

ComfyUIの更新で、昨日まで動いていたworkflowが壊れることがあります。Developmentは最新commitを含む一方、未解決の問題が入る可能性があります。Stableは新機能の反映が遅れる代わりに安定性を優先します。最初の失敗後にすべてを更新するより、バージョン記録とロールバック経路を用意する方が確実です。

1. stableまたはdevelopmentを選ぶ前にバックアップする

更新前チェックリスト：

1. 現在のComfyUI commitを記録します

   • Git：git rev-parse HEAD
   • PortableまたはDesktop：versionとupdate channelを記録します

2. PythonとPyTorchを記録します

   • Python：python --version
   • PyTorch：python -c "import torch; print(torch.__version__)"
   • NVIDIA環境ではnvidia-smiでdriverを記録します

3. 重要なcustom nodeのバージョンを記録します

   • Managerからノード一覧をexportまたは保存します
   • 本番で使うノードのcommit hashを記録します

4. workflowと設定をバックアップします

   • 重要なworkflow JSONを別ディレクトリへexportします
   • extra_model_paths.yaml、Desktopのextra models config、重要なuser dataを保存します

StableとDevelopment：

version type	特徴	適した用途
Stable / Release	安定化されたreleaseで、新機能は遅れる場合がある	本番環境と長期運用
Development / Latest	最新commitを含み、新機能を早く使える	新モデル、新機能、ノード互換性のテスト
固定commit	既知の状態に固定され、後続修正は自動で入らない	一時的なロールバック、回帰切り分け、再現

インストール方式別の更新方針：

インストール方式	方針
Desktop	既定はstable channel。必要に応じて現在の管理UIでchannelを選ぶ
Portable	update_comfyui_stable.batはstable、update_comfyui.batはdevelopmentを追う
Manual Git	git pull後、ComfyUI環境内でrequirements.txtを更新する。commit切り替えで戻せる

変わりやすい情報：スクリプト名とDesktop設定は現在のUpdate ComfyUI文書で確認してください。

2. 更新後に壊れた場合のロールバック

最初に、ComfyUI core、単一custom node、Python環境のどこが変わったか特定します。

変更箇所の分類：

1. ComfyUI coreだけを更新した場合

   • --disable-all-custom-nodesでcoreが起動するか確認します
   • custom nodeに対応更新が必要か調べます

2. 一つのcustom nodeだけを更新した場合

   • そのノードを以前のversionに戻します
   • または無効化し、ComfyUIが回復するか確認します

3. 依存関係を更新した場合

   • Python、PyTorch、重要packageのversionを再確認します
   • Portableのupdate_comfyui_and_python_dependencies.batは全依存関係を再インストールします。公式文書は、競合や特定versionに固定されたcustom nodeの破損リスクを警告しています

Gitでのロールバック：

# 最近のcommitを表示
git log --oneline

# 動作確認済みのcommitへ切り替え
git checkout <commit-hash>

# 対応するComfyUI環境内でのみ依存関係を更新
pip install -r requirements.txt

PortableとDesktopのロールバック手順は変わる可能性があります。更新前バックアップの復元を優先し、現在の公式更新文書に従ってください。最初にアンインストールすると、回帰を調べるためのバージョンと設定の証拠が失われます。

custom nodeのissueに含める情報：

• 完全なエラーと再現手順
• ComfyUI、Python、PyTorch、GPU driverのversion
• --disable-all-custom-nodesテストの結果
• 更新前後のcoreまたはノードversion

次に読むトピック

環境が安定したら、該当するComfyUIトピックに進みます。

1. 共有workflowを再現する

   • workflowをimportし、ノードとモデルを追加し、loaderを接続します
   • ComfyUIワークフロー再利用ガイドを参照してください

2. VRAM使用量を減らす

   • OOMやVRAMピークから、--lowvram、VAE、モデル量子化の選択へ進みます
   • ComfyUIの低VRAM・高速化実践を参照してください

3. アップスケールとインペイント

   • FaceDetailer、Impact Packなどのpost-processing nodeを使うworkflowを復旧します
   • ComfyUIのアップスケールとインペイントを参照してください

4. 動画を生成する

   • 動画workflow、動画VAE、最後のexport問題へ進みます
   • ComfyUI動画生成入門を参照してください

5. APIで一括自動化する

   • API format、/prompt、node_errors、queue管理を扱います
   • ComfyUI APIで画像を一括生成する方法を参照してください

6. モデルとVAEを選ぶ

   • checkpoint、VAE、LoRA、loader構成を比較します
   • Stable Diffusionモデル選定ガイドを参照してください