エラー解決

【ComfyUI】カスタムノードが読み込まれない時の原因と確実な解決手順7選

· 11分で読めます · 1 閲覧

問題の概要：カスタムノードがワークフローに表示されない

ComfyUIはその柔軟性から、多くの開発者によって様々な機能を追加する「カスタムノード」が公開されています。しかし、これらのノードをインストールしたにもかかわらず、ComfyUIのノード一覧（右クリックメニュー）に表示されず、ワークフローで使用できないという問題が頻繁に発生します。この問題は、環境構築の初期段階で遭遇することが多く、AI画像生成のワークフロー構築を大きく妨げます。

具体的には、以下のような状況が発生します：

  • カスタムノードを`custom_nodes`フォルダに配置したが、ComfyUIを起動しても該当ノードが表示されない
  • 起動時のターミナル/コンソールにエラーメッセージが表示される（例：`ModuleNotFoundError: No module named ‘some_dependency’`）
  • 「Add Node」メニュー内の該当カテゴリが存在しない、またはノード名がグレーアウトしている
  • ワークフロー(.json)を読み込んだ際に、`Load failed` や `Unknown node type` といったエラーが発生する

原因の解説：なぜカスタムノードは読み込みに失敗するのか？

カスタムノードの読み込み失敗は、単一の原因ではなく、複数の要因が重なって発生することがほとんどです。主な原因は以下の4つに分類できます。

1. 依存パッケージの不足

ほとんどのカスタムノードは、PyTorchやPillowなどの基本ライブラリ以外に、独自のPythonパッケージに依存しています。ノードの開発者が`requirements.txt`や`install.py`を用意していても、環境によっては自動インストールが失敗することがあります。

2. Pythonパスの問題

ComfyUIは起動時に`custom_nodes`フォルダ内の各ノードフォルダをPythonのモジュールとして読み込みます。しかし、ノードフォルダの構造が規約（`__init__.py`の存在や、ノードクラスを定義するファイル名）に沿っていない場合、正しく認識されません。

3. ノードの互換性問題

カスタムノードは特定のバージョンのComfyUI APIを前提に開発されています。ComfyUI本体をアップデートした後や、逆に古いノードを新しいComfyUIで使用しようとすると、内部APIの変更により読み込みに失敗します。

4. ファイルの配置ミスと権限問題

単純にファイルを誤った場所に配置していたり、Windows/Mac/Linuxにおけるファイルシステムの権限設定により、Pythonがモジュールを読み込めないケースもあります。

解決方法：ステップバイステップのトラブルシューティング

以下の手順を上から順に試し、問題を系統的に解決していきましょう。

ステップ1：ComfyUIの再起動とエラーログの確認

まず、ComfyUIを完全に終了し、再起動します。その後、ターミナル（コマンドプロンプト）に表示される起動ログを最初から最後まで注意深く確認してください。ここに根本的なエラーが表示されていることが多いです。

# ComfyUIの起動コマンド例（Windows）
cd C:ComfyUI_windows_portable
python main.py

# エラーログの例
ERROR:    Could not import node "ComfyUI-Custom-Sampler" due to:
ModuleNotFoundError: No module named 'some_special_lib'

ステップ2：依存パッケージの手動インストール

エラーログに特定のモジュール名が表示された場合、そのパッケージを手動でインストールします。カスタムノードのフォルダ内に`requirements.txt`がある場合は、それを利用します。

# カスタムノードのディレクトリに移動
cd ComfyUI/custom_nodes/ComfyUI-Example-Node

# requirements.txtからインストール（仮想環境をアクティベート後）
pip install -r requirements.txt

# または、エラーメッセージに表示された単一パッケージをインストール
pip install some_special_lib

ステップ3：ノードフォルダ構造の確認

カスタムノードは正しい構造で配置されている必要があります。以下のような構造になっているか確認してください。

ComfyUI/
├── custom_nodes/
│   └── ComfyUI-Node-Name/  # ノードのメインフォルダ
│       ├── __init__.py     # 必須（空でも可）
│       ├── node.py         # ノードクラスを定義するメインファイル（名前は異なる場合も）
│       ├── requirements.txt
│       └── ... (その他のファイル)
└── ... (ComfyUI本体のファイル)

`__init__.py`ファイルがない場合は、空のファイルを作成することで解決することがあります。

ステップ4：ComfyUIの管理機能を使用したインストール

ComfyUIには、Managerと呼ばれるカスタムノード（e.g., ComfyUI-Manager）があり、これを使用するとワンクリックでノードをインストール・更新でき、依存関係も自動で処理される場合があります。未導入の場合は導入を検討してください。

ステップ5：Pythonパスの確認と修正

稀に、システムのPYTHONPATHが正しく設定されていない場合があります。ComfyUIの起動スクリプト（`main.py`）と同じディレクトリから起動していることを確認するか、以下のようにパスを明示的に追加する方法もあります（通常は不要）。

# main.pyの先頭付近に追記する（最終手段）
import sys
sys.path.insert(0, '/path/to/your/custom_nodes')

ステップ6：ノードの互換性を確認し、バージョンを調整する

GitHubなどのノード配布ページで、対象のComfyUIバージョンが記載されているかを確認します。問題が発生した場合は、以下のいずれかを試します。

  • カスタムノードを最新版に更新する（`git pull`）
  • ノードのリポジトリの「Issues」ページで同様の問題がないか検索する
  • やむを得ない場合、ComfyUI本体をノードが対応するバージョンにダウングレードする

ステップ7：クリーンインストール

上記すべてで解決しない場合、以下の手順でクリーンな状態から再インストールします。

1. カスタムノードフォルダをバックアップ後、ComfyUI/custom_nodes/ から該当ノードのフォルダを削除。
2. ComfyUIを再起動し、正常に起動することを確認。
3. カスタムノードを再度ダウンロード/クローンし、custom_nodesフォルダに配置。
4. 依存パッケージを明示的にインストール。
5. ComfyUIを再起動。

コード例・コマンド例：具体的なトラブルシューティングセッション

仮に「ComfyUI-Advanced-ControlNet」というノードが読み込まれない場合の、具体的な対話例です。

# 1. エラーログを確認
ERROR:    Failed to load node: "ComfyUI-Advanced-ControlNet" (C:ComfyUIcustom_nodesComfyUI-Advanced-ControlNet)
ImportError: cannot import name 'ControlNetModel' from 'diffusers'

# 2. エラーから、diffusersライブラリに関連する問題と推測。
# 3. 該当ノードのフォルダに移動し、requirements.txtを確認。
cd custom_nodes/ComfyUI-Advanced-ControlNet
cat requirements.txt
# 出力例: diffusers>=0.20.0

# 4. 現在のdiffusersバージョンを確認。
pip show diffusers
# バージョンが0.19.3など、要求より古い場合がある。

# 5. バージョンをアップグレード。
pip install --upgrade diffusers

# 6. ComfyUIを再起動し、ノードが表示されるか確認。

まとめ・補足情報

ComfyUIのカスタムノード読み込み問題は、そのほとんどが「依存関係」と「互換性」の2点に集約されます。最初にターミナルのエラーメッセージを丁寧に読む習慣をつけるだけで、解決までの時間を大幅に短縮できます。

予防策として、以下の点を心がけることをお勧めします：

  • カスタムノードは、ComfyUI-Managerを通じて可能な限りインストールする。
  • 新しいノードを試す際は、まずそのGitHubリポジトリのREADMEやIssuesを一読し、既知の問題や特別なインストール手順がないか確認する。
  • ComfyUI本体とカスタムノードのバージョンを定期的に更新し、極端なバージョンの乖離を防ぐ。
  • 仮想環境（venvやconda）を使用してプロジェクトごとに環境を分離することで、パッケージの衝突を防ぐ。

ComfyUIのエコシステムは急速に発展しており、ノード同士の依存関係も複雑化しています。問題が解決しない場合は、DiscordコミュニティやGitHubのIssueで積極的に質問してみましょう。多くの場合、開発者やコミュニティメンバーが具体的な解決策を提示してくれます。

この記事は役に立ちましたか？