ComfyUIカスタムノード更新後に起動しない原因と対処手順

ComfyUI Manager でカスタムノードをまとめて更新したあと、次の起動で UI が真っ白になる、もしくはサーバーがクラッシュする——このパターンは ComfyUI を使っていると遭遇しやすいトラブルのひとつです。エラーの種類は限られており、ログを読めば多くの場合は原因を絞り込めます。この記事では、ログの読み方から依存パッケージの修復、問題ノードの切り分けまでを、コマンドを交えて順番に説明します。

起動失敗の主な原因3パターン

ComfyUI は起動時に custom_nodes/ 以下のディレクトリを走査し、各ノードの __init__.py をインポートします。インポートに失敗した場合、そのノードはスキップされますが、エラーの種類や実装によってはサーバー全体が止まります。まずログを確認するのが最初のステップです。

ログを読んで原因を特定する

フォアグラウンドで起動してエラーを目視する

systemd や nohup でバックグラウンド起動している場合は、一度フォアグラウンドで動かすと Traceback がそのまま画面に出ます。

cd ~/ComfyUI
source venv/bin/activate    # venv を使っている場合
python main.py --port 8188

Traceback (most recent call last): から始まるブロックを探してください。最後の行がエラーの種類と内容です。その行がそのまま検索キーワードになります。

ログをファイルに保存して検索する

エラーが流れて見切れる場合は、標準出力と標準エラー両方をファイルに保存します。

python main.py --port 8188 2>&1 | tee /tmp/comfy_debug.log
grep -n "Error\|Traceback\|FAILED" /tmp/comfy_debug.log

ログ中の custom_nodes/ノード名/ という文字列が、エラー箇所のノードを示しています。複数ノードを同時に更新した場合は、複数のエラーが積み重なっていることもあります。

依存パッケージの競合を解消する（ImportError 対処）

ImportError: cannot import name 'XXX' や ModuleNotFoundError: No module named 'xxx' はパッケージ起因がほとんどです。

requirements.txt を再インストールする

エラーログから対象ノードのフォルダ名を確認し、そのノードの依存をインストールし直します。

cd ~/ComfyUI/custom_nodes/対象ノードのフォルダ名
# venv の pip を明示的に指定する
../../venv/bin/pip install -r requirements.txt

venv の pip ではなく global の pip が実行されると ComfyUI の環境に反映されません。which pip でパスを確認してから実行してください。インストール後に ComfyUI を再起動して確認します。

バージョン競合が起きているとき

別のカスタムノードが同じパッケージの異なるバージョンを要求していることがあります。エラーに含まれるパッケージ名で現在のバージョンを確認します。

pip show パッケージ名

問題ノードの GitHub リポジトリの requirements.txt や README で必要バージョンを確認し、バージョンを指定してインストールします。

pip install パッケージ名==X.Y.Z

ただし、バージョンを下げると別のノードが壊れることがあります。その場合は優先度の低いほうのノードを無効化するのが現実的な判断です。

torch・xformers は別途注意が必要

torch や xformers は CUDA 対応ビルドと CPU ビルドが別パッケージです。pip install torch と素直に実行すると CPU 版が入ることがあります。PyTorch 公式サイト（pytorch.org）の install selector で OS と CUDA バージョンを選んで生成されたコマンドを使ってください。

# CUDA 12.1 の場合の例（執筆時点。公式サイトで最新コマンドを確認してください）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

ComfyUI 本体との非互換に対処する（AttributeError 対処）

AttributeError や TypeError が出る場合、ComfyUI 本体の API が変わり、古いカスタムノードのコードが追いついていないケースが考えられます。

対処の順序

1. ノードのリポジトリで Issues を確認する — 同じエラーが報告されていることが多く、修正 PR が出ているかどうかわかります
2. ノードを更新する — Manager から Update をかけるか、手動で git pull → pip install -r requirements.txt を実行します
3. ComfyUI 本体を一時的にロールバックする — ノード側の対応を待つ間、本体を動いていたバージョンに戻す方法もあります

cd ~/ComfyUI
git log --oneline -10             # 直近のコミット履歴を確認
git checkout コミットハッシュ      # 動いていた時点に戻す

ロールバックは暫定対応です。ノードが修正されたら git checkout main で最新に戻してください。

問題のカスタムノードを切り分けて無効化する

複数のノードを同時に更新した場合や、どのノードが原因か分からないときは、バイナリサーチで絞り込みます。

ComfyUI Manager がある場合

Manager を開き「Disable All Custom Nodes」でいったん全無効化 → ComfyUI を再起動して起動を確認 → ノードを1つずつ有効に戻す、という手順が確実です。

ファイルシステムで無効化する

Manager なしで行う場合、フォルダ名を変えて ComfyUI の読み込みを回避します。

cd ~/ComfyUI/custom_nodes

# まず全ノードを無効化
for d in */; do mv "$d" "${d%/}.disabled"; done

# ComfyUI が起動することを確認してから、1つずつ戻す
mv 対象ノード名.disabled 対象ノード名

起動できることを確認しながらノードを1つずつ戻し、失敗したタイミングで最後に戻したノードが原因です。

SyntaxError はリポジトリをリセットする

SyntaxError や IndentationError でファイル自体が壊れているときは、リポジトリをクリーンな状態に戻します。git pull の途中でネットワークが切れた場合などに起こることがあります。

cd ~/ComfyUI/custom_nodes/対象ノード名
git fetch origin
git reset --hard origin/main    # デフォルトブランチ名は各リポジトリで確認
pip install -r requirements.txt

git reset --hard はローカルの変更をすべて破棄します。設定ファイルを独自に編集している場合は先にバックアップを取ってください。

VRAM 管理や複数モデル運用でのトラブルはComfyUI VRAM 12GBで複数モデルを切り替える設定と上限も参考にしてください。

まとめ

カスタムノード更新後の起動失敗は、次の順序で対処すると多くのケースで対処の見通しが立ちます。

次の行動として、まずターミナルを開いて python main.py でフォアグラウンド起動を試してください。Traceback の最後の行がそのまま解決策を指しています。