Evolution API não gera QR Code? Veja por que não conecta ao WhatsApp
Evolution API não gera QR Code ou não conecta? Diagnostique sessão, WhatsApp Web, Docker, volumes, PostgreSQL, Redis e recursos da VPS Linux.
A instância foi criada, mas o QR Code não aparece. Ou ele aparece, o WhatsApp faz a leitura e a Evolution API continua desconectada. A origem nem sempre está no WhatsApp.
O fluxo envolve Evolution API → sessão → WhatsApp → persistência → banco/Redis → container → servidor. Verificar cada camada em ordem evita apagar dados que poderiam explicar a falha.
Primeiro: qual é exatamente o estado da instância?
Instância existente não significa WhatsApp conectado. No canal baseado em Baileys, o código atual registra estados como connecting, open e close. A interface ou integração pode apresentar rótulos equivalentes, conforme a versão.
Criada
O cadastro existe, mas a sessão pode ainda não ter iniciado ou concluído o pareamento.
connecting
A conexão está em andamento e pode estar aguardando leitura ou finalização do vínculo.
open
O socket está conectado; ainda convém validar estabilidade e funcionamento da integração.
close ou logout
Close descreve o fechamento da conexão. Logout é um motivo/evento específico e pode exigir novo pareamento.
QR Code não aparece
Quando a Evolution API não gera QR Code, as hipóteses incluem criação incompleta, serviço ainda inicializando, container com erro, sessão antiga inconsistente, banco inacessível, Redis indisponível, variável incorreta ou incompatibilidade na versão instalada.
Antes de recriar a instância, confirme estado e reinícios do container, leia os logs, valide banco e Redis quando usados e observe memória, CPU e disco da VPS. Compare também a imagem em execução com a versão esperada.
QR Code aparece, mas o WhatsApp não conecta
O QR Code possui validade limitada e pode ser substituído durante a tentativa. Sem assumir um tempo fixo, confirme se o código lido ainda é o atual e se o pareamento terminou no telefone e na API.
O vínculo pode falhar se o container reiniciar, a comunicação for interrompida, a sessão não for salva ou o estado ficar inconsistente. Registre o horário da leitura e relacione-o ao evento connection.update, ao estado retornado e aos logs do mesmo intervalo.
Versão do WhatsApp Web desatualizada ou incompatível
O canal Baileys depende do protocolo usado pelo WhatsApp Web. Uma incompatibilidade pode impedir o QR Code, interromper o vínculo ou derrubar novas sessões, inclusive quando instâncias antigas ainda funcionam.
Verifique a versão da Evolution API, a dependência Baileys adotada por ela, o changelog, releases e issues recentes da mesma versão. O código oficial atual consulta a versão do WhatsApp Web, mas o comportamento depende da release instalada.
Evolution API desatualizada e protocolo do WhatsApp Web incompatível são problemas relacionados, mas não necessariamente a mesma causa.
Evolution API conecta e desconecta logo depois
Aqui é essencial separar pareamento de manutenção da sessão. Se chegou a open e depois fechou, investigue sessão corrompida, reinício do container, armazenamento perdido, falta de memória, banco ou Redis indisponível, conflito de instância, logout pelo WhatsApp e atualização incompatível.
O estado de fechamento e seu motivo ajudam a decidir se a queda nasceu na infraestrutura, no transporte ou na invalidação da sessão. Não trate toda desconexão como banimento.
Persistência: o problema que aparece depois de reiniciar
Um ambiente pode funcionar até o primeiro reboot ou redeploy. Se o WhatsApp conecta e exige novo pareamento depois que o container volta, confirme onde dados de sessão e arquivos necessários são armazenados e se o volume Docker está montado no destino esperado.
O Docker não preserva automaticamente a camada gravável de um container substituído; volumes existem para manter dados fora desse ciclo. Banco e demais armazenamentos também precisam sobreviver e estar acessíveis. Persistência incorreta é uma hipótese importante, mas logout ou sessão invalidada podem produzir sintoma parecido.
Container reiniciando no Docker, Coolify ou Easypanel
Reinícios contínuos impedem a inicialização e o pareamento estáveis. As causas possíveis incluem falta de memória, configuração obrigatória ausente, falha no banco, Redis fora do ar, erro de inicialização, imagem incompatível, healthcheck inadequado ou processo encerrando com falha.
No Evolution API Docker, Coolify ou Easypanel, anote a contagem e o horário dos reinícios e preserve os logs imediatamente anteriores ao encerramento. São mais informativos do que o log gerado depois que o serviço volta.
PostgreSQL ou Redis podem impedir a conexão?
Depende da versão e da arquitetura. Credenciais incorretas, hostname ou porta errados, containers em redes diferentes, DNS interno falhando, limite de conexões, banco indisponível, Redis offline ou inicialização incompleta podem afetar o funcionamento.
Não culpe esses serviços apenas porque fazem parte do ambiente. Confirme conectividade, saúde e mensagens dos logs da API, do PostgreSQL e do Redis no mesmo horário.
Evolution API atualizada e conexão parou
Depois de uma atualização, revise changelog, alterações de configuração, imagem Docker, dependências, migrations, banco e mudanças em Baileys ou no fluxo de conexão. Confirme que o container executa a tag planejada e que a migração terminou.
Atualizar produção sem backup e validação aumenta o risco. Um downgrade também pode ser incompatível com migrations ou dados recentes; não o trate como resposta automática.
O problema está na Evolution API ou no WhatsApp?
Mais próximo da infraestrutura
Container reiniciando, banco inacessível, volume perdido, logs de inicialização com erro ou servidor sem recursos.
Mais próximo da sessão ou WhatsApp
Logout explícito, dispositivo removido, sessão invalidada ou pareamento que não foi concluído.
Esses sinais orientam a investigação; causa confirmada exige o estado da instância, o motivo da desconexão e os logs.
O que verificar nos logs
Procure erros de conexão ou autenticação, falha ao carregar sessão, indisponibilidade de banco ou Redis, reinicialização e mensagens imediatamente anteriores ao fechamento. Correlacione horário, nome da instância e reinícios.
Clicar repetidamente em “reconectar” muda o estado sem necessariamente revelar a origem. Salve as evidências antes de uma nova tentativa.
Checklist rápido de diagnóstico
- 1A instância foi criada com o canal e as opções esperadas?
- 2O QR Code é gerado ou a contagem permanece sem mudança?
- 3O container está estável e sem reinícios recorrentes?
- 4Os logs mostram erro antes da falha ou desconexão?
- 5A VPS possui memória, disco e CPU disponíveis?
- 6O banco está acessível pela rede e credenciais configuradas?
- 7O Redis está funcionando quando faz parte da arquitetura?
- 8Volumes e demais armazenamentos são realmente persistentes?
- 9A sessão permanece depois de um reinício controlado?
- 10A versão instalada corresponde à configuração e às migrations?
- 11O estado indica conexão, fechamento, logout ou pareamento incompleto?
- 12Evolution API, Baileys e protocolo do WhatsApp Web estão compatíveis?
O que evitar
Não apague volumes, banco ou sessões antes de coletar logs. Evite recriar instâncias, reinstalar tudo, alternar atualização e downgrade, modificar várias variáveis ou reiniciar a VPS continuamente. Remover persistência elimina dados e pistas úteis.
Quando procurar suporte especializado
Procure suporte Evolution API quando o QR Code nunca aparece, a conexão cai continuamente, a sessão some após reiniciar, várias instâncias falham ou o container reinicia. Produção parada, falha após atualização e erros envolvendo Docker, PostgreSQL ou Redis também justificam escalar.
Para outros sintomas, consulte o guia geral sobre problemas e soluções da Evolution API.
Fontes técnicas oficiais
Conteúdo revisado em 20 de agosto de 2026. Estados, integrações e armazenamento podem variar conforme versão e canal utilizados.
Perguntas frequentes
Por que a Evolution API não gera QR Code?
A causa pode estar na inicialização da instância, no container, na configuração, na sessão anterior, no banco, no Redis ou na compatibilidade da versão. O log deve confirmar a camada afetada.
Por que o QR Code aparece, mas o WhatsApp não conecta?
O código pode ter expirado, o pareamento pode não ter terminado, o container pode ter reiniciado ou a sessão pode ter ficado inconsistente durante a vinculação.
Por que a Evolution API desconecta depois de reiniciar?
Isso pode indicar sessão não persistida, volume incorreto, banco indisponível ou encerramento explícito da sessão. Logs e armazenamento precisam ser verificados antes de recriar a instância.
Docker ou volume podem fazer a Evolution API perder a sessão?
Sim. Se dados necessários forem gravados apenas na camada descartável do container ou o volume estiver incorreto, eles podem desaparecer no redeploy. Essa é uma hipótese, não a única causa possível.
A Jupiter TI oferece suporte remoto para Evolution API?
Sim. A Jupiter TI analisa Evolution API, QR Code, sessão, Docker, Coolify, Easypanel, PostgreSQL, Redis, volumes, redes, logs, atualizações e integração com n8n.
Jupiter TI
Sua Evolution API não gera QR Code, não conecta ou perde a sessão constantemente?
A Jupiter TI oferece diagnóstico e suporte remoto para Evolution API, QR Code, sessão, Docker, Coolify, Easypanel, PostgreSQL, Redis, volumes, redes, logs, recursos da VPS, atualizações e integração com n8n. Em vez de recriar instâncias ou reinstalar o ambiente por tentativa e erro, podemos analisar em qual camada está a falha.