mcpField
C
comfyui-troubleshooter

comfyui-troubleshooter

github.com/mckruzクリエイティブ・メディア921.0k 回インストール32 週間前に更新
リポジトリ

comfyui-troubleshooter について

ComfyUI のユーザーやエージェント向けに、サーバー、ワークフロー、出力品質、性能の問題を扱うトラブルシューティングスキルです。エラーのパターンや導入状況をもとに、確認事項と対処法を提案します。

主な機能

  1. 014 種類の問題を分類
  2. 02既知の対処法とエラーを照合
  3. 03モデルとカスタムノードを確認
  4. 04品質と性能の調整を提案

活用シーン

  1. 01ComfyUI の接続障害の診断
  2. 02ワークフローのノードやモデル不足の解決
  3. 03出力の乱れや生成速度低下への対処

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/mckruz/comfyui-expert --skill comfyui-troubleshooter

インストール後、Claude Code で/comfyui-troubleshooterを入力して読み込まれたか確認します。

詳細

ComfyUI トラブルシューティング

ComfyUI の問題を、サーバーエラー、ワークフローエラー、品質の問題、パフォーマンスの問題の 4 つのカテゴリにわたって診断し、解決します。

診断プロセス

ステップ 1：エラーを分類する
カテゴリ症状最初に確認すること
サーバー接続拒否、タイムアウト、クラッシュComfyUI は実行中ですか？/system_stats を確認してください
ワークフローノードエラー、入力の欠落、型の不一致ワークフローをインベントリと照合して検証してください
品質アーティファクト、異なる人物の顔、ぼやけた出力設定（CFG、重み、解像度）を確認してください
パフォーマンスOOM、生成速度の低下、VRAM エラーVRAM 使用量とモデルサイズを確認してください
ステップ 2：コンテキストを収集する

診断の前に、以下を収集してください。

  1. エラーメッセージ（正確なテキスト）
  2. 実行中のワークフロー（またはその説明）
  3. 関連するモデル（チェックポイント、LoRA、ControlNet など）
  4. 設定（CFG、ステップ数、解像度、サンプラー）
  5. ハードウェア（foundation/hardware-profile.md を参照）
  6. インベントリ（state/inventory.json を参照）
ステップ 3：エラーパターンを照合する

エラーデータベースの全項目については、references/troubleshooting.md を参照してください。

すぐに使える修正方法

最もよくあるエラー 10 件

1. "CUDA out of memory" → FP8 を使用する：--fp8_e4m3fn-unet → タイル VAE を有効にする → 解像度を下げる → ComfyUI を再起動する（メモリの断片化を解消します）

2. "Node type not found: {name}" → ComfyUI-Manager からカスタムノードパッケージをインストールする → comfyui-inventory のノードとパッケージの対応表を確認する

3. "Expected scalar type BFloat16 but found Float" → 精度が一致していません。--force-fp16 を追加するか、同じ精度のノードを使用してください

4. 顔が白飛びする／露出オーバーになる → CFG を 4～5 に下げる（InstantID） → ID 手法の重みを下げる → ネガティブ埋め込みにノイズを追加する（35%）

5. "No model found at path" → ファイル名のスペルを確認する（完全一致が必要です） → ファイルが正しいサブディレクトリにあることを確認する → インベントリスキャンを実行して確認する

6. 1024x1024 でウォーターマークのアーティファクトが発生する → 代わりに 1016x1016 または 1020x1020 を使用する

7. 参照画像と同じ人物にならない → より高品質な参照画像を使用する（鮮明で正面を向いているもの） → IP-Adapter の重みを 0.8 以上に上げる → InsightFace antelopev2 がインストールされていることを確認する

8. 動画がちらつく → FaceDetailer のノイズ除去を 0.3 に下げる → 後処理にちらつき除去を追加する → AnimateDiff のコンテキストのオーバーラップを 4 以上に増やす

9. キューが停止している／処理されない → POST /interrupt を送信してキャンセルする → POST /free を送信してモデルをアンロードする → ComfyUI を再起動する

10. 生成が遅い → --lowvram が有効になっているか確認する（RTX 5090 では無効にしてください） → 代わりに --highvram を使用する → cuDNN を 8800 以降に更新する → Wan モデルで SageAttention を有効にする

判断ツリー：品質の問題

OUTPUT LOOKS WRONG
    |
    |-- Faces look wrong
    |   |-- Too smooth/plastic → Add skin texture LoRA (0.2-0.4)
    |   |-- Wrong identity → Increase identity weight, check reference quality
    |   |-- Burned/hot → Lower CFG to 4-5, reduce InstantID weight
    |   |-- Deformed → Add "bad anatomy, deformed" to negative
    |   |-- Different every time → Fix seed, add LoRA for consistency
    |
    |-- Colors wrong
    |   |-- Oversaturated → Lower CFG, add "oversaturated" to negative
    |   |-- Washed out → Check VAE is loaded, try different scheduler
    |   |-- Color shift in video → Add color correction post-processing
    |
    |-- Resolution/sharpness
    |   |-- Blurry → Increase steps (25-30), check resolution matches model
    |   |-- Pixelated → Use proper upscaler (4x-UltraSharp), not resize
    |   |-- Artifacts → Lower denoise, check for model corruption
    |
    |-- Composition
    |   |-- Ignoring prompt → Increase CFG slightly, simplify prompt
    |   |-- Extra limbs/objects → Add to negative prompt, use ControlNet
    |   |-- Wrong pose → Add ControlNet OpenPose with reference

不足している依存関係の解決

ワークフローがインベントリにないものを参照している場合：

カスタムノードが不足している場合
1. Identify package from class_type (see inventory skill's mapping)
2. Suggest: "Open ComfyUI-Manager → Search → Install {package_name}"
3. Alternative: "cd {ComfyUI}/custom_nodes && git clone {repo_url}"
4. Remind: Restart ComfyUI after installation
モデルが不足している場合
1. Look up in references/models.md for download link
2. Provide: exact filename, download URL, target directory
3. For large models (>10GB): suggest HF CLI for reliability
   "huggingface-cli download {repo} {file} --local-dir {path}"
バージョンの非互換性
1. Check ComfyUI version vs node package requirements
2. Suggest: "cd {ComfyUI} && git pull" for ComfyUI update
3. Or: pin specific node version if newest breaks things

エスカレーション

トラブルシューティングで問題が解決しない場合：

  1. ComfyUI の GitHub Issues で既知の不具合を確認する
  2. 該当するノードパッケージの Issues を確認する
  3. r/comfyui でコミュニティの解決策を検索する
  4. エラーの詳細を添えて ComfyUI Discord への投稿を提案する

参考資料

  • references/troubleshooting.md - 解決策を含むエラーデータベース全体
  • state/inventory.json - 現在のインストール状態
  • references/models.md - モデルのダウンロードリンクとパス

コメント

Markdown 対応