ComfyUIのカスタムノードで依存関係が衝突したときの切り分け方

カスタムノードを追加・更新した直後からComfyUIが起動しなくなった場合、いきなりPython環境を作り直したり、すべてのパッケージを更新したりすると、かえって原因を追えなくなる。

まずは壊れる直前に何を変えたかと、最初に出たエラーを残したまま、カスタムノードを減らしていく。

起動ログの最初のエラーを保存する

画面に表示された最後の一行だけでなく、起動ログに出た最初の例外やimport failed周辺を保存する。

同時に次も記録しておく。

ComfyUIのバージョン:
使っているPython環境:
最後に正常起動した日:
直前に追加・更新したカスタムノード:
最初に出たエラー:

あとから何度もパッケージを入れ替える前の状態を残しておくことが重要だ。

ComfyUI Desktop、Portable版、手動インストールでは、Python環境の扱いが同じとは限らない。

別のシステムPythonへpip installしても、ComfyUIが使っている環境には反映されないことがある。逆に、ComfyUI側の環境で無条件にパッケージを更新すると、別のカスタムノードが必要としているバージョンと衝突する場合がある。

まず「どのPythonに対して操作しているのか」を確認してから変更する。

最初に、直前に追加または更新したカスタムノードを無効化し、ComfyUI本体に近い状態で起動する。

そこで起動できるなら、外したノードを一つずつ戻す。

単独では動くノードAとノードBを同時に有効にしたときだけ失敗するなら、両方が要求しているPythonパッケージやバージョンを比較する。

原因候補が絞れたら、次のように記録する。

この形まで絞れれば、配布元の不具合報告で既知の問題を探す場合や、新しく報告する場合にも再現条件を伝えやすい。

依存関係の衝突では、あるノードが新しいパッケージを必要とし、別のノードが古いバージョンを前提にしていることがある。

その状態で一括更新をすると、一方が直って別のノードが壊れることもある。まず衝突する組み合わせを特定し、各ノードの公式な導入手順や対応バージョンを確認する方が安全だ。

カスタムノードは単なる画面部品ではなく、Pythonコードや追加パッケージを実行する。新しく導入する前の安全確認については、カスタムノードの安全チェックを別に確認しておく。

起動しなくなったときは、環境全体を壊して作り直す前に、直前の変更、Python環境、最初のエラー、カスタムノードの組み合わせを順番に絞る方が原因へたどり着きやすい。