Dépanner ComfyUI : nœuds rouges, erreurs VAE et retour de version

Vous ouvrez un workflow partagé et découvrez une rangée de unknown nodes rouges. Vous lancez Install Missing Custom Nodes dans Manager, redémarrez ComfyUI, mais ils restent rouges. Manager n’est pas un outil de réparation universel : il gère le code des nœuds, sans garantir l’installation correcte de toutes leurs dépendances, et il n’installe pas les fichiers de modèle.

Les nœuds rouges ne sont qu’une porte d’entrée du dépannage ComfyUI. L’application peut rester sur loading, l’interface peut être blanche, un workflow jusque-là fonctionnel peut casser après une mise à jour, la sortie VAE peut devenir grise ou noire, ou un modèle copié peut manquer dans un menu déroulant. Ces symptômes renvoient souvent à des conflits de custom nodes, des versions de dépendances, des chemins de modèles, des options de précision ou des pics de VRAM.

Le chemin le plus court part du symptôme : identifiez la couche probable, puis effectuez le test le plus limité qui permette de trancher.

Tableau rapide par symptôme

Le tableau couvre six points d’entrée courants. Repérez le symptôme dans la première colonne, limitez la cause avec la deuxième, puis commencez par la troisième.

Symptôme	Cause la plus probable	Première action
Nœuds rouges / unknown nodes	Custom node absent, nœud renommé ou import en échec	Rechercher le nom dans Manager ou Registry et vérifier Import failed dans la console
Blocage sur loading / page blanche / blank screen	Conflit d’une extension frontend de custom node	Tester python main.py --disable-all-custom-nodes
Prompt execution failed après Queue	Erreur de custom node, problème de modèle ou VRAM insuffisante	Ouvrir Show report et identifier le composant fautif
Sortie VAE grise, blanche, teintée ou noire	VAE incompatible ou précision incorrecte	Vérifier la connexion du VAE loader, les fichiers associés et --fp16-vae
Workflow cassé après mise à jour	Incompatibilité core/custom node ou conflit de dépendances	Identifier ce qui a été mis à jour et examiner les scripts de update
Modèle copié absent du menu	Mauvais chemin ou définitions de nœuds non actualisées	Vérifier le sous-dossier ComfyUI/models/, puis redémarrer ou actualiser

Ne supprimez pas immédiatement l’installation. Sauvegardez workflow, journaux, liste des nœuds et versions avant de modifier l’environnement.

Nœud rouge : custom node ou modèle ?

Un unknown node rouge signifie généralement que ComfyUI ne trouve pas ce type de nœud. Le custom node peut manquer, avoir été renommé ou désactivé, ou échouer pendant l’import de ses dépendances. Un modèle absent disparaît plus souvent du menu du loader ou produit une erreur de modèle à l’exécution. Séparez ces deux classes de panne.

1. Ce que corrige Install Missing dans Manager

Install Missing Custom Nodes de ComfyUI-Manager traite surtout l’absence du code d’un nœud. Manager installe les nœuds via Registry ou un dépôt source, mais les éléments suivants peuvent demander une intervention distincte :

• Les dépendances Python du nœud, comme torch, numpy ou xformers dans requirements.txt
• Les fichiers de modèle : checkpoints, VAE, LoRA et ControlNet
• Les chemins de modèles propres au custom node, indiqués dans son README

Comfy Desktop inclut Manager et l’active par défaut. Dans les installations Portable et Manual actuelles, le nouveau Manager est intégré au core de ComfyUI, mais il faut installer manager_requirements.txt et démarrer avec --enable-manager. Si un nœud n’apparaît pas dans Manager, il peut ne pas être enregistré, ou un problème réseau peut limiter la liste aux données en cache ou locales. Vérifiez le dépôt d’origine avant d’installer un paquet au nom proche.

Suivez cet ordre : chercher Import failed dans la console → chercher le nœud dans Manager ou Registry → vérifier le chemin du modèle. Le processus complet d’import se trouve dans Réutiliser un workflow ComfyUI.

2. Lire correctement Import failed

Lorsque la console affiche Import failed, la fin de la traceback contient généralement le module absent ou la version en conflit. La classe d’erreur dicte la suite :

Arbre de décision :

1. ModuleNotFoundError: No module named 'xxx' → paquet Python absent

   • Ne l’installez pas dans le Python système, mais dans l’environnement Python de ComfyUI
   • Portable : python_embeded\python.exe -m pip install -r custom_nodes\xxx\requirements.txt
   • Desktop et Manual utilisent d’autres chemins ; identifiez l’exécutable Python réellement utilisé par ComfyUI

2. Erreurs torch / CUDA / cuDNN → PyTorch et le backend GPU ne correspondent pas

   • Vérifier PyTorch : python -c "import torch; print(torch.__version__)"
   • Vérifier que le pilote GPU respecte les exigences système actuelles
   • Un nœud peut demander une version de torch incompatible avec celle de ComfyUI

3. Exception dans le custom node → version du nœud ou défaut de code

   • Rechercher la même traceback dans les issues GitHub du nœud
   • Si une nouvelle version a introduit la régression, tester un commit connu comme fonctionnel

Information évolutive : au moment de la mise en paquet, ComfyUI recommande Python 3.13 et propose 3.12 comme solution de repli lorsque certaines dépendances de custom nodes échouent avec 3.13. Les exigences PyTorch et CUDA changent rapidement ; consultez les exigences système actuelles.

3. Installé dans Manager, mais toujours indisponible

L’état « installé » ne prouve pas que le nœud se charge. Après redémarrage, il peut rester rouge ou déclencher un conflit entre torch et torchvision.

Pourquoi un nœud installé peut rester indisponible :

• Une erreur réseau a interrompu le téléchargement du dépôt ou des dépendances
• Les requirements Python n’ont pas été installés dans l’environnement de ComfyUI
• Le nœud est désactivé ou échoue pendant l’import
• Sa version n’est pas compatible avec la version actuelle de ComfyUI

Pourquoi les dépendances entrent en conflit :

• Plusieurs custom nodes exigent des versions différentes de torch, torchvision ou numpy
• Une version strictement fixée dans requirements.txt entre en conflit avec les paquets existants

Ordre de résolution :

1. Lire la dernière traceback complète et la classer avec la section précédente
2. Désactiver ou supprimer le nœud suspect, puis retester ComfyUI
3. Rechercher dans requirements.txt des versions strictes comme torch==2.4.1
4. Si le conflit persiste, ouvrir une issue avec :
   • La traceback complète
   • Le résultat de python main.py --disable-all-custom-nodes
   • Les versions de Python, PyTorch et du pilote GPU

Information évolutive : Manager coexiste sous forme nouvelle, intégrée et legacy. Suivez la documentation actuelle pour les libellés et les menus. Si la cause réelle est OOM ou un pic de VRAM, continuez avec Optimiser ComfyUI pour 6 à 8 Go de VRAM.

4. Chemins de modèles et menus vides

ComfyUI n’inclut pas les poids des modèles. Téléchargez séparément checkpoints, VAE, LoRA, ControlNet et upscalers, puis placez-les dans le sous-dossier correspondant de ComfyUI/models/.

Ordre de vérification si le fichier manque :

1. Bon dossier

   • Checkpoints dans ComfyUI/models/checkpoints/
   • VAE dans ComfyUI/models/vae/
   • LoRA, ControlNet et upscalers dans leurs dossiers de type
   • Si un custom node utilise un autre chemin, suivez son README

2. Redémarrage ou actualisation

   • Redémarrer ComfyUI ou utiliser l’actualisation des définitions prise en charge par l’interface actuelle

3. Intégrité du fichier

   • Comparer sa taille avec la source de téléchargement
   • Retélécharger ou vérifier un fichier incomplet

4. Loader compatible

   • Choisir un loader et un modèle de workflow conçus pour cette famille de modèle
   • FLUX, SD3.x et d’autres architectures récentes peuvent demander des text encoders, VAE et combinaisons de nœuds spécifiques
   • Les chemins d’un custom node peuvent différer des indications génériques de ComfyUI/models/

5. extra_model_paths.yaml

   • Portable et Manual peuvent référencer des bibliothèques externes avec extra_model_paths.yaml ; redémarrer après l’enregistrement
   • Desktop possède son propre fichier de configuration de modèles externes ; utiliser le chemin officiel actuel

Pour l’association entre modèle et VAE, consultez Choisir un modèle Stable Diffusion.

Diagnostiquer un chargement bloqué avec —disable-all-custom-nodes

Quand ComfyUI reste sur loading, affiche une page blanche ou ne rend plus son interface, une extension frontend de custom node est souvent impliquée. --disable-all-custom-nodes permet de savoir rapidement si les custom nodes sont en cause.

1. Démarrer sans custom nodes

Commande :

python main.py --disable-all-custom-nodes

Windows Portable :

Copiez run_nvidia_gpu.bat ou run_cpu.bat, ajoutez --disable-all-custom-nodes à la commande de lancement et enregistrez un script de démarrage sûr séparé.

Interprétation :

• Le problème disparaît sans custom nodes → un custom node est responsable
  • Poursuivre avec une recherche binaire
• Le problème persiste → les custom nodes ne sont pas la cause
  • Vérifier le core ComfyUI, les exigences système, le pilote GPU et Python/PyTorch
  • Vérifier les fichiers de modèle et leurs chemins
  • Rechercher un pic de VRAM avec Optimiser ComfyUI pour 6 à 8 Go de VRAM

Information évolutive : confirmez les options de lancement avec python main.py --help.

2. Isoler le mauvais nœud par recherche binaire

Si le démarrage sûr prouve qu’un custom node est responsable, la recherche binaire réduit les candidats sans deviner.

Principe : déplacer ou activer la moitié des custom nodes à chaque test, observer le résultat et diviser de nouveau le groupe suspect.

Étapes :

1. Sauvegarder ComfyUI/custom_nodes/
2. Déplacer la moitié des dossiers de nœuds vers un répertoire de test temporaire
3. Démarrer ComfyUI et reproduire le problème
4. Interpréter le résultat :
   • Le problème disparaît → le mauvais nœud se trouve dans la moitié déplacée
   • Le problème reste → il se trouve dans la moitié conservée
5. Répéter jusqu’à isoler un nœud ou une petite interaction

Après l’identification :

• Rechercher la même traceback dans les issues GitHub
• Examiner requirements.txt pour les versions strictement fixées
• Mettre à jour, remplacer, désactiver ou supprimer le nœud
• Si une nouvelle version a introduit la régression, tester le commit fonctionnel précédent

Informations à joindre à une issue :

• Version de ComfyUI
• Erreur complète et étapes de reproduction
• Système d’exploitation
• Résultat du test --disable-all-custom-nodes
• Versions de Python, PyTorch, du pilote GPU et matériel

Corriger les sorties VAE grises, noires ou incompatibles

Une sortie grise, blanche, teintée ou noire peut venir d’un VAE incompatible, d’une mauvaise connexion de décodage, de la précision du VAE, de celle de l’attention ou des fichiers propres à un modèle récent. Testez dans cet ordre.

1. Ordre de vérification du VAE

Étapes :

1. Vérifier la connexion du VAE

   • Relier la sortie VAE du checkpoint loader ou d’un VAE loader séparé au nœud de décodage
   • Certains checkpoints incluent un VAE ; d’autres modèles demandent un fichier séparé

2. Associer VAE, modèle et workflow

   • SD1.5, SDXL, FLUX et SD3.x peuvent demander des combinaisons différentes de VAE, text encoder et loader
   • Commencer par le plus petit modèle de workflow officiel ou l’exemple du README du modèle

3. Vérifier --fp16-vae

   • La documentation Startup Flags indique que --fp16-vae peut produire des images noires
   • Le retirer ou tester --fp32-vae / --bf16-vae si le matériel le permet

4. Tester les options de précision

   • --fp32-vae : VAE en pleine précision, généralement plus gourmand en VRAM
   • --bf16-vae : VAE en BF16, avec matériel et backend compatibles
   • --cpu-vae : VAE sur CPU, généralement beaucoup plus lent
   • --force-upcast-attention : teste si l’upcast de l’attention corrige l’image noire ; ce n’est pas un réglage général de qualité

5. Vérifier enfin VRAM, pilotes et dépendances

   • Un pic de VRAM peut interrompre le décodage VAE
   • Vérifier le pilote GPU selon les exigences actuelles
   • Vérifier que PyTorch correspond au backend GPU

Symptômes fréquents :

Symptôme	Cause possible
Gris, blanc ou teinté	Mauvais VAE, mauvais chemin de décodage ou incompatibilité workflow/modèle
Entièrement noir	--fp16-vae, précision de l’attention, pic de VRAM ou combinaison de modèles invalide
Erreur de chargement	VAE endommagé, mauvais chemin ou fichiers incomplets

2. Risque d’image noire avec un VAE fp16

De nombreux tutoriels recommandent --fp16-vae pour réduire l’utilisation des ressources. La référence officielle Startup Flags avertit pourtant qu’il peut produire des images noires. Tenez compte du modèle, du matériel et des journaux.

Options de précision VAE :

Option	Effet	Quand la tester
--fp16-vae	Exécute le VAE en FP16 et réduit souvent les ressources	Peut produire des images noires ; à utiliser avec prudence
--fp32-vae	Exécute le VAE en pleine précision	Utile pour diagnostiquer une image noire, généralement avec plus de VRAM
--bf16-vae	Exécute le VAE en BF16	Demande matériel et backend compatibles
--cpu-vae	Exécute le VAE sur CPU	Test en cas de VRAM limitée, généralement plus lent

Précision de l’attention :

• --force-upcast-attention : teste si l’upcast de l’attention corrige l’image noire
• --dont-upcast-attention : incompatible avec l’option précédente et réservé au débogage

Ordre pratique :

• Ne copiez pas des « options d’accélération » sans lire le symptôme et la sortie console
• Pour une image noire, retirez d’abord --fp16-vae, puis testez selon l’environnement --fp32-vae ou --force-upcast-attention
• Confirmez les noms et valeurs par défaut avec le python main.py --help actuel
• Le parcours complet OOM et faible VRAM se trouve dans Optimiser ComfyUI pour 6 à 8 Go de VRAM

3. Distinguer une incompatibilité VAE/modèle

Si un changement de modèle ou de VAE casse un workflow qui fonctionnait, le modèle, le VAE, le loader ou le modèle de workflow ne correspondent probablement pas. Chaque famille demande ses propres fichiers et nœuds.

Vérification par famille :

Famille	Vérification du VAE	Vérification du loader/workflow
Checkpoint SD1.5	Utiliser le VAE intégré ou un VAE SD1.5 correspondant	Commencer par un workflow de base compatible SD1.5
Checkpoint SDXL	Utiliser le VAE intégré ou un VAE SDXL correspondant	Utiliser un modèle de workflow et un loader compatibles SDXL
FLUX / SD3.x	Préparer VAE et text encoder selon le README	Suivre le modèle officiel ou la documentation du projet

Diagnostic :

1. Vérifier le README du modèle, la page du projet ou le modèle officiel
   • Confirmer le VAE intégré, les poids complémentaires et le loader requis
2. Vérifier les fichiers choisis dans chaque loader
   • Le VAE du menu doit correspondre au modèle et au workflow
3. Reproduire avec le plus petit modèle officiel
   • Retirer les traitements personnalisés, puis reconnecter les nœuds un par un

Correspondance des symptômes :

Symptôme	Cause probable
Gris, blanc ou teinté	VAE, modèle ou chemin de décodage incompatible
Erreur de chargement	VAE endommagé, mauvais chemin ou fichiers incomplets
Workflow minimal fonctionnel, original en échec	Un traitement ou custom node modifie le décodage

Pour les choix détaillés, consultez Choisir un modèle Stable Diffusion.

Stratégie de mise à jour : stable, development, sauvegarde et retour

Une mise à jour ComfyUI peut casser un workflow qui fonctionnait la veille. Development contient les derniers commits, mais peut aussi contenir des problèmes ouverts. Stable privilégie la stabilité au prix d’un certain retard. Des versions notées et un chemin de retour valent mieux qu’une nouvelle mise à jour globale après la première panne.

1. Sauvegarder avant de choisir stable ou development

Liste avant mise à jour :

1. Noter le commit ComfyUI actuel

   • Git : git rev-parse HEAD
   • Portable ou Desktop : noter la version et le canal de mise à jour

2. Noter Python et PyTorch

   • Python : python --version
   • PyTorch : python -c "import torch; print(torch.__version__)"
   • Sur NVIDIA, noter le pilote avec nvidia-smi

3. Noter les versions des custom nodes importants

   • Exporter ou enregistrer la liste de Manager
   • Noter les commits des nœuds critiques en production

4. Sauvegarder workflows et configuration

   • Exporter les fichiers JSON importants vers un répertoire séparé
   • Sauvegarder extra_model_paths.yaml, la configuration Desktop des modèles externes et les données utilisateur importantes

Stable ou Development :

Type de version	Caractéristiques	Usage adapté
Stable / Release	Version stabilisée, parfois en retard sur les fonctions	Production et environnements durables
Development / Latest	Derniers commits et accès anticipé aux fonctions	Test de nouveaux modèles, fonctions et compatibilités
Commit fixé	État connu sans correctifs ultérieurs automatiques	Retour temporaire, isolation d’une régression et reproduction

Stratégie par installation :

Installation	Stratégie
Desktop	Canal stable par défaut ; choisir un autre canal dans l’interface de gestion actuelle si nécessaire
Portable	update_comfyui_stable.bat suit stable, update_comfyui.bat suit development
Manual Git	Exécuter git pull, puis mettre à jour requirements.txt dans l’environnement ComfyUI ; changer de commit pour revenir

Information évolutive : confirmez les noms de scripts et réglages Desktop dans la documentation de mise à jour actuelle.

2. Revenir en arrière après une mise à jour cassée

Identifiez d’abord si le core, un custom node unique ou l’environnement Python a changé.

Classer le changement :

1. Seul le core ComfyUI a été mis à jour

   • Tester si le core démarre avec --disable-all-custom-nodes
   • Vérifier si les custom nodes demandent une version compatible

2. Un seul custom node a été mis à jour

   • Restaurer sa version précédente
   • Ou le désactiver et retester ComfyUI

3. Les dépendances ont été mises à jour

   • Revérifier Python, PyTorch et les paquets critiques
   • update_comfyui_and_python_dependencies.bat de Portable réinstalle toutes les dépendances ; la documentation avertit que cela peut créer des conflits et casser les nœuds liés à des versions précises

Retour Git :

# Afficher les commits récents
git log --oneline

# Revenir à un commit connu comme fonctionnel
git checkout <commit-hash>

# Mettre à jour les dépendances uniquement dans l’environnement ComfyUI correspondant
pip install -r requirements.txt

Les chemins de retour de Portable et Desktop peuvent changer. Restaurez de préférence la sauvegarde préalable et suivez la documentation actuelle. Une désinstallation immédiate supprime les versions et réglages utiles au diagnostic.

Informations pour une issue de custom node :

• Erreur complète et étapes de reproduction
• Versions de ComfyUI, Python, PyTorch et du pilote GPU
• Résultat du test --disable-all-custom-nodes
• Versions du core ou du nœud avant et après la mise à jour

Pour aller plus loin

Une fois l’environnement stable, poursuivez avec le sujet ComfyUI correspondant :

1. Reproduire un workflow partagé

   • Importer le workflow, compléter nœuds et modèles, puis connecter les loaders
   • Voir Réutiliser un workflow ComfyUI

2. Réduire l’usage de la VRAM

   • Passer d’un OOM ou pic de VRAM à --lowvram, au VAE et à la quantification
   • Voir Optimiser ComfyUI pour 6 à 8 Go de VRAM

3. Upscaling et inpainting

   • Restaurer les workflows avec FaceDetailer, Impact Pack et d’autres nœuds de post-traitement
   • Voir Upscaling et inpainting dans ComfyUI

4. Créer des vidéos

   • Traiter les workflows vidéo, les VAE vidéo et les erreurs de dernière étape
   • Voir Créer des vidéos ComfyUI

5. Automatiser avec l’API

   • Utiliser API format, /prompt, node_errors et la gestion de file
   • Voir Automatiser des séries d’images avec l’API ComfyUI

6. Choisir modèles et VAE

   • Comparer checkpoints, VAE, LoRA et configurations de loaders
   • Voir Choisir un modèle Stable Diffusion