troubleshooting

ComfyUI のトラブルシューティングガイド

レンダリングは完了したのに、仕上がりがおかしい（アーティファクト、被写体／ポーズ／色の間違い、ControlNet／マスク／LoRA が反映されない、リファイナーで品質が劣化するなど）場合、エラーではありません。 デバッグレンダーのスキル（action: "skill_read" を指定した list_packs、name: "debug-render"）を使い、中間ステップをプレビューしながら run-to-node（to_node_id を指定した panel_run）で問題のあるステージを特定してください。このガイドの対象は、エラー、OOM、ノード不足によって実行に失敗するケースです。

エラー診断の方針

ワークフローが失敗した場合は、次の手順に従ってください。

1. エラーを取得します。get_history(action="diagnose") を使い、完全なトレースバックと不足しているモデル／ノードを含む実行結果を取得します
2. ログを確認します。get_system_stats (action:"logs") を使い、"error"、"warning"、"traceback" などのキーワードで絞り込みます
3. 失敗したノードを特定します。履歴のレスポンスには、失敗した node_id と node_type が含まれます
4. 入力を照合します。create_workflow (action:"node_info") を使い、失敗したノードが想定する入力スキーマを確認します
5. モデルを確認します。list_local_models を使い、参照されているすべてのモデルファイルが存在することを確認します

メモリ不足（OOM）

エラーパターン

torch.cuda.OutOfMemoryError: CUDA out of memory. Tried to allocate X MiB.
GPU 0 has a total capacity of 24.00 GiB of which X MiB is free.

または：

RuntimeError: CUDA error: out of memory

根本原因

GPU にモデルの重み、中間テンソル、潜在画像を同時に保持するための VRAM が足りません。よくある原因は次のとおりです。

• 高解像度の画像（2048x2048 以上）
• 複数のモデルを同時に読み込んでいる
• VRAM が限られている環境での FP32 精度モデル
• 多数のフレームを使う動画生成（LTXV、AnimateDiff）
• 大きなバッチサイズ

対処法（優先度順）

1. 解像度を下げます。モデル本来の解像度（SD 1.5 は 512、SDXL／Flux は 1024）まで下げてください
2. FP8／FP16 量子化モデルを使います。FP8 Flux モデルは約 8GB で、FP16 の約 24GB より少なくて済みます
   • FP8 バリアントを検索します：download_model({ action: "search", query: "flux fp8" })、または "sdxl fp8" を指定します
3. 起動フラグ（VRAM の段階的な設定）。ComfyUI の CLI フラグを使ってオフロードします。
   • --lowvram はテキストエンコーダーやモデルの一部を CPU にオフロードします
   • --novram は極端なオフロードを行います。長時間の動画生成（LTX 2／WAN）での OOM に特に有効です
   • --cache-none は何もキャッシュしません（RAM／VRAM の使用量が最小になります）。--novram と組み合わせてください
   • --reserve-vram N は、GPU が低速な共有 VRAM にあふれないよう、N GB を確保します（Windows）。通常は 2～4 に設定します
   • 実行が停止したり、断続的に OOM が発生したりする場合は、--disable-smart-memory を使うと RAM へのオフロードが強制されます
   • 全設定の一覧とレシピ： comfyui-launch-flags
4. 生成の合間に VRAM を解放します。ComfyUI は通常、自動で管理しますが、再起動すると解放されずに残ったメモリがクリアされます
5. タイル化 VAE デコードを使います。高解像度の画像では、VAE デコードのステップをタイル化してください
   • ノード：VAEDecode の代わりに VAEDecodeTiled を使います
   • 画像をタイルに分割してそれぞれを個別にデコードし、最後に結合します
6. バッチサイズを小さくします。EmptyLatentImage の batch_size を 1 に設定します
7. 複数のモデルを避けます。2 つの完全なチェックポイントを同時に読み込まず、1 つのチェックポイントと LoRA を使ってください
8. LTXV／動画では、24GB のカードで必ず FP8 量子化済みの動画モデルを使ってください

VRAM の推定値

モデル	FP32	FP16	FP8
SD 1.5	約 4GB	約 2GB	約 1GB
SDXL	約 12GB	約 6GB	約 3GB
Flux Dev	約 48GB	約 24GB	約 12GB
Flux Schnell	約 48GB	約 24GB	約 12GB
LTXV	約 20GB 以上	約 10GB 以上	約 6GB 以上

起動フラグ — VRAM／キャッシュ／Attention／精度

ComfyUI の起動フラグは、速度と VRAM 使用量のトレードオフを調整します。検出された GPU に合わせて設定してください（パネルオーケストレーターは、環境ブロック内に VRAM／GPU／torch／sage を報告します。そこから適切な段階を選んでください）。フラグは ComfyUI を起動するプロセス（エージェントではなく、--panel-orchestrator コマンドまたは connect コマンドの ComfyUI）に設定します。

VRAM モード（カードのサイズに合わせて 1 つ選択）

フラグ	カード	動作
--gpu-only	16GB 以上	すべて（CLIP/VAE/UNet）を GPU 上に保持します。最速で、VRAM を最大限使用します
--highvram	12～16GB	使用後もモデルを GPU 上に常駐させ、CPU にはオフロードしません
--normalvram	8～12GB	標準的なバランスです。アイドル時は CPU RAM にアンロードします
--lowvram	6～8GB	UNet を分割し、積極的に CPU へオフロードします。速度は低下します
--novram	4～6GB	極端に分割・オフロードします。lowvram でも OOM が発生する場合や、長時間の動画向けです
--cpu	4GB 未満／GPU なし	CPU のみ（非常に低速）

--reserve-vram N（GB）は、OS や他のアプリ向けに余裕を確保します。 実行中に断続的に OOM が発生する場合は、値を増やしてください（VAE デコードや音声の往復処理で使用量が急増します）。

キャッシュ（RAM 使用量と再実行速度）

フラグ	効果
--cache-classic	デフォルトの積極的なキャッシュ（再実行が最速、RAM 使用量が最大）
--cache-lru N	直近 N 個のノード結果を保持します（RAM 使用量に上限あり）
--cache-ram N	キャッシュを N GB の余裕容量に制限します
--cache-none	キャッシュなし。RAM 使用量は最小限ですが、すべてのノードを再実行します

アテンション（速度と互換性）

フラグ	備考
--use-sage-attention	推奨 — 高速かつ効率的です（SageAttention と Triton が必要です。triton-sageattention を参照）
--use-flash-attention	対応 GPU では非常に高速です
--use-pytorch-cross-attention	PyTorch 2.x のネイティブ実装です。互換性が最も高くなります
--use-split-cross-attention	VRAM 使用量は減りますが、速度は低下します
--use-quad-cross-attention	二次未満の最適化です
（省略）	利用可能な場合は xFormers を自動選択します

精度（UNet）

フラグ	効果
--fp16-unet	半精度。VRAM 使用量は約 50％です
--bf16-unet	BFloat16。バランスに優れています（新しい GPU 向け）
--fp8_e4m3fn-unet	8 ビット浮動小数点。節約効果が最大です（最新の GPU 向け）

一般的な設定例：

• RTX 4090/5090（24～32GB）：--gpu-only --use-sage-attention --cache-classic
• 12～16GB：--highvram --use-sage-attention（または、大きなモデルには --fp8_e4m3fn-unet）
• 8GB：--normalvram --use-sage-attention --cache-lru 20
• 6GB：--lowvram --use-split-cross-attention --cache-none
• 長時間の動画で OOM が発生する場合：--novram --reserve-vram 2

デバイスの不一致

エラーパターン

RuntimeError: Expected all tensors to be on the same device, but found at least
two devices, cuda:0 and cpu!

根本原因

CPU 上のテンソルと GPU 上のテンソルが結合されています。通常、次のような場合に発生します。

• カスタムノードがテンソルを正しいデバイスに移動しない
• モデルのオフロードにより、モデルの一部が CPU 上に配置された
• ノードが CPU テンソルを生成する一方で、後続のノードは GPU テンソルを想定している

解決方法

1. 特定のカスタムノードでエラーが発生するか確認します。そのノードを更新するか、置き換えてください
2. --lowvram または --cpu を使用している場合、一部のノードは CPU へのオフロードに対応していないことがあります
3. ComfyUI を再起動して、デバイスの状態をリセットします
4. デバイス処理を修正した新しいバージョンのカスタムノードがないか確認します

ノードが見つからない

エラーパターン

Cannot find node class 'NodeClassName'

または、実行レスポンス内：

"error": {"type": "node_not_found", "message": "Cannot find node class 'X'"}

根本原因

ワークフローが、インストールされていないノードタイプを参照しています。次のような場合に発生します。

• カスタムノードパックがインストールされていない
• カスタムノードパックはインストールされているが、読み込みに失敗した（インポートエラー）
• パックの更新でノード名が変更または削除された

解決方法

1. ノードパックを検索します。

   search_custom_nodes(action="search", query="NodeClassName")
   

2. ComfyUI Manager またはレジストリからインストールします
3. ログでインポートエラーを確認します。

   get_system_stats (action:"logs")(keyword="import")
   get_system_stats (action:"logs")(keyword="error")
   

   インポートエラーから、不足している Python 依存関係がわかることがよくあります
4. 不足している Python 依存関係をインストールします。カスタムノードで pip パッケージが必要な場合：

   pip install missing-package
   

5. カスタムノードをインストールした後は、ComfyUI を再起動します。ノードは起動時に読み込まれます

NaN テンソルエラー

エラーパターン

RuntimeError: Input contains NaN

または、ログに NaN の警告が表示され、生成画像が単色のグレーやノイズになります。

根本原因

拡散処理中の数値的不安定性です。一般的な原因：

• CFG スケールが高すぎます。15～20 を超えると、数値オーバーフローが発生することがあります
• モデルの重みが破損しています。ダウンロードの破損や、互換性のないマージが原因です
• FP16 のオーバーフローです。一部の演算は半精度でオーバーフローします
• 互換性のない LoRA です。異なるベースモデル向けに学習された LoRA が原因です

修正方法

1. CFGを下げます。SD 1.5／SDXLではCFG 7.0、Fluxでは1.0を試してください
2. FP32 VAEを使用します。一部のVAEはFP16でNaNを生成します。vae-ft-mse-840000-ema-pruned.safetensors（FP32）に切り替えてください
3. LoRAを取り除きます。原因を特定するため、LoRAを使わずにテストしてください
4. モデルを再ダウンロードします。ハッシュ検証で破損したファイルを検出できます
5. LoRAの互換性を確認します。LoRAはベースモデルの系列に一致している必要があります

Dtypeの不一致

エラーパターン

RuntimeError: expected scalar type Float but found Half

または：

RuntimeError: expected scalar type Half but found Float

または：

RuntimeError: Input type (float) and bias type (c10::Half) should be the same

根本原因

モデルのコンポーネントが、ある精度（FP32／FP16）を想定しているのに、別の精度を受け取っています。最もよくある原因は次のとおりです。

• VAEの精度の不一致（FP16モデル＋FP32 VAE、またはその逆）
• 混合精度のLoRA
• 特定のdtypeを強制するカスタムノード

修正方法

1. 別のVAEを使用します。チェックポイント内蔵のVAEではなく、明示的にFP32 VAEを読み込みます
   • ノード：VAELoaderとvae-ft-mse-840000-ema-pruned.safetensors
2. 精度を一致させます。モデルがFP16の場合は、全体を通してFP16互換ノードを使用します
3. VAEのデコードをFP32に強制します。一部のノードパックにはVAEDecodeFP32ノードがあります
4. ComfyUIの設定を確認します。--force-fp32フラグはすべてをFP32に強制します（VRAMの使用量が増加します）

CLIPトークンの上限超過

エラーパターン

明示的なエラーはありません。警告なしにプロンプトが77トークンで切り詰められ、後半に記述した詳細は無視されます。

症状

• 長いプロンプトの後半部分が画像に反映されない
• 描写テキストを追加しても出力が変わらない
• 前半のトークンを削除すると、後半のトークンが突然反映される

修正方法

1. BREAKトークンを使用します。自然な区切りでプロンプトを分割します：

   subject description, pose, clothing, setting
   BREAK
   lighting, style, quality, camera angle
   

2. CLIPTextEncodeSDXLを使用します。SDXLのデュアルCLIPは、77トークンのチャンクを2つ処理します
3. 重要なトークンを優先します。最も重要な描写を先頭に配置します
4. 不要な語句を減らします。可能であれば冠詞や前置詞を削除します
5. 埋め込みを使用します。テキスト反転を使って、複雑な概念を単一のトークンにまとめます

黒い画像

エラーパターン

実行時にエラーはありません。ワークフローは「成功」しますが、完全に黒い、またはほぼ黒い画像が生成されます。

根本原因と修正方法

原因	診断	修正方法
denoise = 0	KSamplerの入力を確認	txt2imgではdenoiseを1.0、img2imgでは0.5～0.8に設定します
cfg = 0	KSamplerの入力を確認	CFGをSD 1.5では7.0、Fluxでは1.0に設定します
steps = 0	KSamplerの入力を確認	stepsを標準モデルでは20以上、ターボモデルでは4以上に設定します
VAEが正しくない	VAEがモデルに一致していない	モデル系列に合ったVAEを使用します
プロンプトが空	CLIPTextEncodeのテキストが空	テキストプロンプトを追加します
スケジューラーが正しくない	スケジューラーとサンプラーの組み合わせに互換性がない	"normal"スケジューラーと"euler"サンプラーを試します
シードの衝突	発生頻度は極めて低い	シード値を変更します
FP16 VAEのオーバーフロー	VAEのデコードで黒い画像が生成される	FP32 VAEまたはVAEDecodeTiledを使用します

簡易診断チェックリスト

1. denoiseが0より大きいことを確認します（txt2imgでは1.0にします）
2. cfgが0より大きいことを確認します（SD 1.5では7.0、Fluxでは1.0にします）
3. stepsが0より大きいことを確認します（標準モデルでは20、ターボモデルでは4にします）
4. ポジティブプロンプトが空でないことを確認します
5. 別のシードを試します
6. 動作確認済みのサンプラーとスケジューラーの組み合わせを試します：euler + normal

接続タイプのエラー

エラーパターン

Output type 'IMAGE' doesn't match input type 'LATENT'

または：

Required input 'model' of type 'MODEL' but got connection of type 'CLIP'

根本原因

ノードの誤った出力スロットを、互換性のない入力に接続しています。多くの場合、出力インデックスの誤りが原因です。

修正方法

1. 出力インデックスを確認します。create_workflow (action:"node_info")を使用して、正確な出力順を確認します
   • CheckpointLoaderSimpleの出力：0=MODEL、1=CLIP、2=VAE
   • インデックスを間違えた場合：["1", 0]はMODEL、["1", 1]はCLIPを返します
2. 接続形式を確認します。["nodeId", outputIndex]の形式で、ノードIDは文字列、インデックスは整数です
3. データ型の流れを確認します。パイプラインでは、正しい型の連鎖に従う必要があります：

   MODEL → KSampler
   CLIP → CLIPTextEncode → CONDITIONING → KSampler
   LATENT → KSampler → LATENT → VAEDecode → IMAGE
   VAE → VAEDecode, VAEEncode
   

モデル読み込みエラー

エラーパターン

FileNotFoundError: [Errno 2] No such file or directory: 'models/checkpoints/model.safetensors'

または：

SafetensorError: Error reading file: invalid header

または：

RuntimeError: PytorchStreamReader failed reading zip archive

根本原因

• ファイルが見つかりません。参照先のパスにモデルファイルがありません
• ダウンロードファイルが破損しています。不完全または損傷したファイルです
• 形式が正しくありません。ファイルが有効な safetensors／pickle／checkpoint 形式ではありません

修正方法

1. モデルが存在することを確認します：list_local_models({ action: "list", model_type: "checkpoints" })
2. 正確なファイル名を確認します。ワークフロー内のモデル名は、ファイル名と完全に一致する必要があります（大文字と小文字を区別します）
3. 再ダウンロードします。ハッシュが一致しない場合や破損している場合：

   download_model({ action: "download", url: "...", target_subfolder: "checkpoints" })
   

4. ファイルサイズを確認します。1KB の safetensors ファイルは破損しています。再ダウンロードしてください
5. サブフォルダーを確認します。モデルは正しいサブフォルダー（checkpoints/、loras/、vae/ など）に配置する必要があります

Torch／CUDA バージョンエラー

エラーパターン

RuntimeError: CUDA error: no kernel image is available for execution on the device

または：

ImportError: cannot import name 'xxx' from 'torch'

または：

AssertionError: Torch not compiled with CUDA enabled

根本原因

PyTorch と CUDA のバージョンに互換性がありません。通常、次のような場合に発生します。

• CUDA ツールキットに対応するバージョンを揃えずに PyTorch を更新した
• PyTorch のバージョンをダウングレードまたは変更するカスタムノードをインストールした
• CPU 専用の PyTorch がインストールされる pip install を実行した

修正方法

1. 現在のバージョンを確認します：

   get_system_stats()  # Shows PyTorch version and CUDA version
   

2. CUDA が利用可能か確認します。Python で torch.cuda.is_available() を実行します
3. CUDA 対応の PyTorch を再インストールします。CUDA のバージョンに合ったインストールコマンドを pytorch.org で確認してください
4. PyTorch のバージョンを固定します。修正後は、PyTorch を変更する可能性がある pip install コマンドを実行しないでください
5. ComfyUI にバンドルされた venv を使用します。ComfyUI Desktop には、事前設定済みの Python 環境が付属しています

ComfyUI Desktop と CLI の違い

主な違い

項目	ComfyUI Desktop	ComfyUI CLI
デフォルトポート	8000	8188
Python	埋め込み型（バンドル済み）	システム／venv の Python
インストール先	AppData/Local/Programs/ComfyUI/	クローンした場所
カスタムノード	Documents/ComfyUI/custom_nodes/	リポジトリ内の ./custom_nodes/
モデル	Documents/ComfyUI/models/	リポジトリ内の ./models/
設定	共有パス用の extra_model_paths.yaml	同じ
更新	アプリ内の自動アップデーター	git pull

よくある問題

• ポートが違います。MCP ツールのデフォルトは 8188 です。Desktop を使用している場合は、ポート 8000 に設定してください
• パスがわかりにくいです。Desktop ではユーザーデータとアプリケーションファイルが別々に管理されています
• カスタムノードの pip インストール。Desktop の埋め込み Python は PATH に登録されていない場合があります。venv 内にインストールしてください

エラー別のデバッグコマンド

ワークフローの失敗 — 詳細を取得

get_history(action="list")                       # Most recent execution
get_history(action="list", prompt_id="abc-123")  # Specific execution
get_history(action="diagnose")                   # Why the last run failed

応答には次の情報が含まれます。

• status.status_str：「success」または「error」
• status.messages：タイムスタンプ付きの実行メッセージ
• outputs：ノードの出力（画像など）
• 失敗したノードのエラートレースバック

サーバーの状態を確認

get_system_stats()    # GPU info, VRAM, Python/PyTorch versions
queue(action="list")  # Running and pending jobs
get_system_stats (action:"logs")(max_lines=50, keyword="error")  # Recent error logs

ノードの利用可否を確認

create_workflow(action="node_info", node_type="KSampler")        # Check specific node
create_workflow(action="node_info", node_type="ControlNetApply")  # Verify custom nodes loaded

モデルを確認

list_local_models({ action: "list", model_type: "checkpoints" })   # Installed checkpoints
list_local_models({ action: "list", model_type: "loras" })         # Installed LoRAs
list_local_models({ action: "list", model_type: "controlnet" })    # Installed ControlNets

クイックリファレンス：エラーと修正方法

エラーメッセージ（一部）	最も可能性の高い修正方法
CUDA out of memory	解像度を下げ、FP8 モデルを使用します。VRAM の段階的な対処：--lowvram → --novram --cache-none → --reserve-vram N（起動フラグ）
Expected all tensors on same device	カスタムノードを更新し、ComfyUI を再起動します
Cannot find node class	ノードパックをインストールし、ComfyUI を再起動します
Input contains NaN	CFG を下げ、FP32 VAE を使用し、LoRA を削除します
expected scalar type Float but found Half	FP32 VAE を使用するか、--force-fp32 を指定します
No such file or directory（モデル）	ファイル名を確認し、モデルを再ダウンロードします
invalid header（safetensors）	再ダウンロードします。ファイルが破損しています
CUDA error: no kernel image	CUDA のバージョンに合った PyTorch を再インストールします
画像が黒く、エラーがない	denoise > 0、cfg > 0、steps > 0 であることと、プロンプトが空でないことを確認します
画像が乱れている／ノイズが多い	モデルと VAE の組み合わせ、またはサンプラーの設定が正しくありません
ポート 8188 で Connection refused	ComfyUI が起動していないか、Desktop（ポート 8000）を使用しています
Prompt outputs failed validation	ノードの入力がスキーマと一致していません。create_workflow (action:"node_info") を確認してください

ソース

• 公式： ベンダーのエラーカタログとして見つかったものはありません。起動フラグ名は comfyui-launch-flags（upstream cli_args.py）と照合しています。
• 実測： ComfyUI の障害を観察して作成した、エラーと対処法の表です。