Resolver erros do ComfyUI: nós vermelhos, VAE e versões

Você abre um workflow compartilhado e encontra uma fileira de unknown nodes vermelhos. Executa Install Missing Custom Nodes no Manager, reinicia o ComfyUI e eles continuam vermelhos. O Manager não é uma ferramenta universal de reparo: ele administra o código dos nós, mas não garante a instalação correta de todas as dependências nem baixa os arquivos de modelo.

Nós vermelhos são apenas uma porta de entrada para o diagnóstico do ComfyUI. O aplicativo pode ficar em loading, a interface pode aparecer em branco, um workflow que funcionava pode quebrar depois de uma atualização, a saída VAE pode ficar cinza ou preta, ou um modelo copiado pode não aparecer no menu suspenso. Esses sintomas normalmente apontam para conflitos de custom nodes, versões de dependências, caminhos de modelos, opções de precisão ou picos de VRAM.

O caminho mais curto começa pelo sintoma: identifique a camada provável e faça o menor teste capaz de confirmar ou descartar a hipótese.

Tabela rápida por sintoma

A tabela reúne seis pontos de entrada comuns. Encontre o sintoma na primeira coluna, limite a causa com a segunda e comece pela terceira.

Sintoma	Causa mais provável	Primeira ação
Nós vermelhos / unknown nodes	Custom node ausente, nó renomeado ou falha de import	Procurar o nome no Manager ou Registry e verificar Import failed no console
Travado em loading / página em branco / blank screen	Conflito de uma extensão frontend de custom node	Testar python main.py --disable-all-custom-nodes
Prompt execution failed depois de Queue	Erro de custom node, problema de modelo ou VRAM insuficiente	Abrir Show report e identificar o componente que falhou
Saída VAE cinza, branca, colorida ou preta	VAE incompatível ou precisão incorreta	Verificar a conexão do VAE loader, os arquivos associados e --fp16-vae
Workflow quebrado depois de atualizar	Incompatibilidade entre core e custom node ou conflito de dependências	Identificar o que foi atualizado e examinar os scripts de update
Modelo copiado não aparece no menu	Caminho incorreto ou definições de nós desatualizadas	Conferir a subpasta em ComfyUI/models/ e depois reiniciar ou atualizar

Não apague a instalação imediatamente. Salve o workflow, os logs, a lista de nós e as versões antes de modificar o ambiente.

Nó vermelho: custom node ou modelo?

Um unknown node vermelho normalmente significa que o ComfyUI não encontra aquele tipo de nó. O custom node pode estar ausente, ter sido renomeado, estar desativado ou falhar durante o import das dependências. Já um modelo ausente costuma desaparecer do menu do loader ou gerar um erro de modelo na execução. Separe essas duas classes de falha.

1. O que o Install Missing do Manager corrige

O Install Missing Custom Nodes do ComfyUI-Manager resolve principalmente a ausência do código de um nó. O Manager instala nós pelo Registry ou por um repositório de origem, mas estes itens podem exigir intervenção separada:

• As dependências Python do nó, como torch, numpy ou xformers em requirements.txt
• Os arquivos de modelo: checkpoints, VAE, LoRA e ControlNet
• Os caminhos de modelos específicos do custom node, descritos no README

O Comfy Desktop inclui o Manager e o ativa por padrão. Nas instalações atuais Portable e Manual, o novo Manager está integrado ao core do ComfyUI, mas é preciso instalar manager_requirements.txt e iniciar com --enable-manager. Se um nó não aparecer no Manager, talvez não esteja registrado ou um problema de rede limite a lista a dados locais ou em cache. Confirme o repositório original antes de instalar um pacote de nome parecido.

Siga esta ordem: procurar Import failed no console → procurar o nó no Manager ou Registry → verificar o caminho do modelo. O processo completo de importação está em Reutilizar um workflow do ComfyUI.

2. Como interpretar Import failed

Quando o console mostra Import failed, o fim do traceback normalmente contém o módulo ausente ou a versão em conflito. A classe do erro define a próxima ação:

Árvore de decisão:

1. ModuleNotFoundError: No module named 'xxx' → pacote Python ausente

   • Não instale no Python do sistema, mas no ambiente Python do ComfyUI
   • Portable: python_embeded\python.exe -m pip install -r custom_nodes\xxx\requirements.txt
   • Desktop e Manual usam outros caminhos; identifique o executável Python realmente usado pelo ComfyUI

2. Erros de torch / CUDA / cuDNN → PyTorch e o backend da GPU não correspondem

   • Verificar o PyTorch: python -c "import torch; print(torch.__version__)"
   • Confirmar se o driver da GPU atende aos requisitos atuais do sistema
   • Um nó pode exigir uma versão de torch incompatível com a do ComfyUI

3. Exceção dentro do custom node → versão do nó ou defeito de código

   • Procurar o mesmo traceback nas issues do GitHub do nó
   • Se uma versão nova introduziu a regressão, testar um commit conhecido como funcional

Informação sujeita a mudança: no momento do empacotamento, o ComfyUI recomenda Python 3.13 e oferece 3.12 como alternativa quando algumas dependências de custom nodes falham com 3.13. Os requisitos de PyTorch e CUDA mudam rapidamente; consulte os requisitos atuais do sistema.

3. Instalado no Manager, mas ainda indisponível

O status “instalado” não prova que o nó carrega. Depois da reinicialização, ele pode continuar vermelho ou provocar um conflito entre torch e torchvision.

Por que um nó instalado pode continuar indisponível:

• Um erro de rede interrompeu o download do repositório ou das dependências
• Os requirements Python não foram instalados no ambiente do ComfyUI
• O nó está desativado ou falha durante o import
• A versão dele não é compatível com a versão atual do ComfyUI

Por que as dependências entram em conflito:

• Vários custom nodes exigem versões diferentes de torch, torchvision ou numpy
• Uma versão fixada estritamente em requirements.txt conflita com os pacotes existentes

Ordem de correção:

1. Ler o último traceback completo e classificá-lo com a seção anterior
2. Desativar ou remover o nó suspeito e testar o ComfyUI novamente
3. Procurar versões rígidas como torch==2.4.1 em requirements.txt
4. Se o conflito continuar, abrir uma issue com:
   • O traceback completo
   • O resultado de python main.py --disable-all-custom-nodes
   • As versões de Python, PyTorch e do driver da GPU

Informação sujeita a mudança: o Manager existe nas formas nova integrada e legacy. Siga a documentação atual para rótulos e menus. Se a causa real for OOM ou pico de VRAM, continue em Otimizar o ComfyUI para 6 a 8 GB de VRAM.

4. Caminhos de modelos e menus vazios

O ComfyUI não inclui os pesos dos modelos. Baixe separadamente checkpoints, VAE, LoRA, ControlNet e upscalers e coloque cada um na subpasta correspondente de ComfyUI/models/.

Ordem de verificação quando o arquivo não aparece:

1. Pasta correta

   • Checkpoints em ComfyUI/models/checkpoints/
   • VAE em ComfyUI/models/vae/
   • LoRA, ControlNet e upscalers nas pastas de cada tipo
   • Se um custom node usar outro caminho, siga o README dele

2. Reinicialização ou atualização

   • Reiniciar o ComfyUI ou usar a atualização de definições disponível na interface atual

3. Integridade do arquivo

   • Comparar o tamanho com a fonte do download
   • Baixar novamente ou verificar um arquivo incompleto

4. Loader compatível

   • Escolher um loader e um template de workflow feitos para aquela família de modelos
   • FLUX, SD3.x e outras arquiteturas recentes podem exigir text encoders, VAE e combinações de nós específicas
   • Os caminhos de um custom node podem diferir das orientações gerais de ComfyUI/models/

5. extra_model_paths.yaml

   • Portable e Manual podem referenciar bibliotecas externas com extra_model_paths.yaml; reinicie depois de salvar
   • Desktop tem seu próprio arquivo de configuração de modelos externos; use o caminho oficial atual

Para combinar modelo e VAE, consulte Escolher um modelo de Stable Diffusion.

Diagnosticar um carregamento travado com —disable-all-custom-nodes

Quando o ComfyUI fica em loading, mostra uma página em branco ou deixa de renderizar a interface, uma extensão frontend de custom node costuma estar envolvida. --disable-all-custom-nodes permite descobrir rapidamente se os custom nodes são a causa.

1. Iniciar sem custom nodes

Comando:

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

Windows Portable:

Copie run_nvidia_gpu.bat ou run_cpu.bat, acrescente --disable-all-custom-nodes ao comando de início e salve um script separado de inicialização segura.

Interpretação:

• O problema desaparece sem custom nodes → um custom node é responsável
  • Continue com uma busca binária
• O problema persiste → os custom nodes não são a causa
  • Verifique o core do ComfyUI, os requisitos do sistema, o driver da GPU e Python/PyTorch
  • Verifique os arquivos de modelo e seus caminhos
  • Procure um pico de VRAM em Otimizar o ComfyUI para 6 a 8 GB de VRAM

Informação sujeita a mudança: confirme as opções de inicialização com python main.py --help.

2. Isolar o nó problemático por busca binária

Se a inicialização segura provar que um custom node é responsável, a busca binária reduz os candidatos sem adivinhação.

Princípio: mova ou ative metade dos custom nodes em cada teste, observe o resultado e divida novamente o grupo suspeito.

Etapas:

1. Fazer backup de ComfyUI/custom_nodes/
2. Mover metade das pastas de nós para um diretório temporário de teste
3. Iniciar o ComfyUI e reproduzir o problema
4. Interpretar o resultado:
   • O problema desaparece → o nó problemático está na metade movida
   • O problema permanece → ele está na metade mantida
5. Repetir até isolar um nó ou uma pequena interação

Depois de identificar:

• Procurar o mesmo traceback nas issues do GitHub
• Examinar requirements.txt em busca de versões fixadas estritamente
• Atualizar, substituir, desativar ou remover o nó
• Se uma versão nova introduziu a regressão, testar o commit funcional anterior

Informações para incluir em uma issue:

• Versão do ComfyUI
• Erro completo e etapas de reprodução
• Sistema operacional
• Resultado do teste --disable-all-custom-nodes
• Versões de Python, PyTorch, driver da GPU e hardware

Corrigir saídas VAE cinza, pretas ou incompatíveis

Uma saída cinza, branca, colorida ou preta pode vir de um VAE incompatível, uma conexão incorreta de decodificação, a precisão do VAE ou da atenção, ou arquivos específicos de um modelo recente. Teste nesta ordem.

1. Ordem de verificação do VAE

Etapas:

1. Verificar a conexão do VAE

   • Conectar a saída VAE do checkpoint loader ou de um VAE loader separado ao nó de decodificação
   • Alguns checkpoints incluem um VAE; outros modelos exigem um arquivo separado

2. Combinar VAE, modelo e workflow

   • SD1.5, SDXL, FLUX e SD3.x podem exigir combinações diferentes de VAE, text encoder e loader
   • Começar pelo menor template oficial de workflow ou pelo exemplo do README do modelo

3. Verificar --fp16-vae

   • A documentação Startup Flags informa que --fp16-vae pode produzir imagens pretas
   • Remover a opção ou testar --fp32-vae / --bf16-vae se o hardware permitir

4. Testar opções de precisão

   • --fp32-vae: executa o VAE com precisão total e geralmente usa mais VRAM
   • --bf16-vae: executa o VAE em BF16, com hardware e backend compatíveis
   • --cpu-vae: executa o VAE na CPU e geralmente é muito mais lento
   • --force-upcast-attention: testa se o upcast da atenção corrige a imagem preta; não é um ajuste geral de qualidade

5. Por último, verificar VRAM, drivers e dependências

   • Um pico de VRAM pode interromper a decodificação VAE
   • Verificar o driver da GPU conforme os requisitos atuais
   • Confirmar que o PyTorch corresponde ao backend da GPU

Sintomas comuns:

Sintoma	Causa possível
Cinza, branco ou colorido	VAE incorreto, caminho de decodificação errado ou incompatibilidade entre workflow e modelo
Totalmente preto	--fp16-vae, precisão da atenção, pico de VRAM ou combinação inválida de modelos
Erro de carregamento	VAE danificado, caminho incorreto ou arquivos incompletos

2. Risco de imagem preta com VAE fp16

Muitos tutoriais recomendam --fp16-vae para reduzir o uso de recursos. Porém, a referência oficial Startup Flags alerta que essa opção pode produzir imagens pretas. Decida com base no modelo, no hardware e nos logs.

Opções de precisão do VAE:

Opção	Efeito	Quando testar
--fp16-vae	Executa o VAE em FP16 e geralmente reduz recursos	Pode produzir imagens pretas; use com cuidado
--fp32-vae	Executa o VAE com precisão total	Útil para diagnosticar imagens pretas, normalmente com mais VRAM
--bf16-vae	Executa o VAE em BF16	Exige hardware e backend compatíveis
--cpu-vae	Executa o VAE na CPU	Teste para VRAM limitada; normalmente é mais lento

Precisão da atenção:

• --force-upcast-attention: testa se o upcast da atenção corrige a imagem preta
• --dont-upcast-attention: é incompatível com a opção anterior e serve apenas para depuração

Ordem prática:

• Não copie “opções de aceleração” sem ler o sintoma e a saída do console
• Para imagem preta, remova primeiro --fp16-vae; depois teste --fp32-vae ou --force-upcast-attention conforme o ambiente
• Confirme nomes e valores padrão com o python main.py --help atual
• O fluxo completo para OOM e pouca VRAM está em Otimizar o ComfyUI para 6 a 8 GB de VRAM

3. Distinguir incompatibilidade entre VAE e modelo

Se trocar o modelo ou o VAE quebrar um workflow que funcionava, provavelmente modelo, VAE, loader ou template do workflow não correspondem. Cada família exige seus próprios arquivos e nós.

Verificação por família:

Família	Verificação do VAE	Verificação do loader/workflow
Checkpoint SD1.5	Usar o VAE integrado ou um VAE compatível com SD1.5	Começar por um workflow básico compatível com SD1.5
Checkpoint SDXL	Usar o VAE integrado ou um VAE compatível com SDXL	Usar template de workflow e loader compatíveis com SDXL
FLUX / SD3.x	Preparar o VAE e o text encoder conforme o README	Seguir o template oficial ou a documentação do projeto

Diagnóstico:

1. Verificar o README do modelo, a página do projeto ou o template oficial
   • Confirmar o VAE integrado, os pesos adicionais e o loader necessário
2. Verificar os arquivos escolhidos em cada loader
   • O VAE do menu deve corresponder ao modelo e ao workflow
3. Reproduzir com o menor template oficial
   • Remover o processamento personalizado e reconectar os nós um por um

Correspondência dos sintomas:

Sintoma	Causa provável
Cinza, branco ou colorido	VAE, modelo ou caminho de decodificação incompatível
Erro de carregamento	VAE danificado, caminho incorreto ou arquivos incompletos
Workflow mínimo funciona, original falha	Um processamento ou custom node altera a decodificação

Para escolhas detalhadas, consulte Escolher um modelo de Stable Diffusion.

Estratégia de atualização: stable, development, backup e reversão

Uma atualização do ComfyUI pode quebrar um workflow que funcionava no dia anterior. Development contém os commits mais recentes, mas também pode incluir problemas abertos. Stable prioriza a estabilidade com algum atraso. Registrar versões e manter um caminho de volta é melhor do que executar outra atualização geral após a primeira falha.

1. Fazer backup antes de escolher stable ou development

Lista antes da atualização:

1. Registrar o commit atual do ComfyUI

   • Git: git rev-parse HEAD
   • Portable ou Desktop: registrar a versão e o canal de atualização

2. Registrar Python e PyTorch

   • Python: python --version
   • PyTorch: python -c "import torch; print(torch.__version__)"
   • Na NVIDIA, registrar o driver com nvidia-smi

3. Registrar as versões dos custom nodes importantes

   • Exportar ou salvar a lista do Manager
   • Registrar os commits dos nós críticos para produção

4. Fazer backup dos workflows e da configuração

   • Exportar os arquivos JSON importantes para outro diretório
   • Salvar extra_model_paths.yaml, a configuração de modelos externos do Desktop e os dados importantes do usuário

Stable ou Development:

Tipo de versão	Características	Uso indicado
Stable / Release	Versão estabilizada, talvez atrasada em relação a alguns recursos	Produção e ambientes duradouros
Development / Latest	Commits mais recentes e acesso antecipado a recursos	Testar novos modelos, recursos e compatibilidade
Commit fixado	Estado conhecido sem correções automáticas posteriores	Reversão temporária, isolamento de regressão e reprodução

Estratégia por instalação:

Instalação	Estratégia
Desktop	Canal stable por padrão; escolher outro pela interface de gerenciamento atual quando necessário
Portable	update_comfyui_stable.bat acompanha stable e update_comfyui.bat acompanha development
Manual Git	Executar git pull e atualizar requirements.txt no ambiente do ComfyUI; trocar de commit para voltar

Informação sujeita a mudança: confirme os nomes dos scripts e as configurações do Desktop na documentação de atualização atual.

2. Reverter depois de uma atualização quebrada

Primeiro identifique se mudou o core, apenas um custom node ou o ambiente Python.

Classificar a mudança:

1. Somente o core do ComfyUI foi atualizado

   • Testar se o core inicia com --disable-all-custom-nodes
   • Verificar se os custom nodes exigem uma versão compatível

2. Apenas um custom node foi atualizado

   • Restaurar a versão anterior dele
   • Ou desativá-lo e testar o ComfyUI novamente

3. As dependências foram atualizadas

   • Verificar novamente Python, PyTorch e os pacotes críticos
   • O update_comfyui_and_python_dependencies.bat do Portable reinstala todas as dependências; a documentação alerta que isso pode criar conflitos e quebrar nós vinculados a versões específicas

Reversão com Git:

# Mostrar commits recentes
git log --oneline

# Voltar a um commit conhecido como funcional
git checkout <commit-hash>

# Atualizar dependências somente no ambiente correspondente do ComfyUI
pip install -r requirements.txt

Os caminhos de reversão do Portable e Desktop podem mudar. Prefira restaurar o backup anterior e seguir a documentação atual. Desinstalar imediatamente remove versões e configurações úteis para o diagnóstico.

Informações para uma issue de custom node:

• Erro completo e etapas para reproduzir
• Versões do ComfyUI, Python, PyTorch e driver da GPU
• Resultado do teste --disable-all-custom-nodes
• Versões do core ou do nó antes e depois da atualização

Próximos passos

Quando o ambiente estiver estável, continue com o tópico correspondente do ComfyUI:

1. Reproduzir um workflow compartilhado

   • Importar o workflow, completar nós e modelos e conectar os loaders
   • Ver Reutilizar um workflow do ComfyUI

2. Reduzir o uso de VRAM

   • Passar de OOM ou pico de VRAM para --lowvram, VAE e quantização
   • Ver Otimizar o ComfyUI para 6 a 8 GB de VRAM

3. Upscaling e inpainting

   • Restaurar workflows com FaceDetailer, Impact Pack e outros nós de pós-processamento
   • Ver Upscaling e inpainting no ComfyUI

4. Criar vídeos

   • Resolver workflows de vídeo, VAE de vídeo e erros da etapa final
   • Ver Criar vídeos com o ComfyUI

5. Automatizar com a API

   • Usar API format, /prompt, node_errors e gerenciamento de filas
   • Ver Automatizar lotes de imagens com a API do ComfyUI

6. Escolher modelos e VAE

   • Comparar checkpoints, VAE, LoRA e configurações de loaders
   • Ver Escolher um modelo de Stable Diffusion