Evolution API não gera QR Code ou não conecta: causas e soluções

Quando a Evolution API não gera QR Code ou não conecta, a causa quase sempre está em um destes pontos: imagem desatualizada, mudança do lado do WhatsApp que a Baileys ainda não acompanhou, instância presa depois de logout, cache e sincronização sobrecarregando a conexão, rede ou proxy, ou limite de aparelhos no celular. Abaixo está o checklist com as oito verificações, na ordem em que eu faria, com o link da issue no repositório oficial de cada caso.

Consultei o GitHub e a documentação da Evolution em novembro de 2026. Um aviso antes: várias soluções vêm de relatos de usuários nas issues, não de correções lançadas. Onde for assim, eu digo.

Primeiro, onde fica a Evolution agora

O repositório mudou de EvolutionAPI/evolution-api para evolution-foundation/evolution-api, e a documentação foi para docs.evolutionfoundation.com.br. Os links antigos redirecionam. Na consulta, a última versão estável era a 2.3.7, de dezembro de 2025. A 2.4.0 ainda estava em pré-lançamento e, segundo as notas da 2.4.0-rc1, exige ativação de licença: sem ativar, a API responde erro 503. Se você subiu para a 2.4.0 e nada funciona, comece por aí.

Como checar o estado da instância

Antes de mexer em algo, veja o que a API diz. Pela referência oficial de instâncias:

• GET /instance/connectionState/{instancia} devolve open, close ou connecting;
• GET /instance/connect/{instancia} devolve o QR (base64, code) e um contador count;
• DELETE /instance/logout/{instancia} e DELETE /instance/delete/{instancia} desconectam e apagam.

Se o connect volta só {"count": 0} e nada de QR, você está no sintoma mais relatado.

Checklist: Evolution API não gera QR Code ou não conecta

1. O QR aparece, você lê e o celular diz que não foi possível conectar

A descrição do PR 2727, enviado por um colaborador, diz que, por volta de 28 de julho de 2026, o WhatsApp adicionou uma etapa nova no pareamento depois da leitura do QR, e a Baileys descarta essa etapa, então o pareamento nunca conclui. Sessões que já estavam conectadas continuam funcionando; o problema é conectar aparelho novo.

• Como checar: você está na 2.3.7, o QR aparece, a leitura falha e um QR novo surge.
• Como corrigir: na consulta, não havia versão oficial com a correção. Existem o PR 2727 (para a develop) e o PR 2759 (para a linha 2.3.x), ambos abertos. Enquanto não forem aceitos e lançados, não são correção oficial. Acompanhe esses PRs e o CHANGELOG da próxima release.

2. O endpoint connect só devolve count 0

É o primeiro sintoma listado na issue 2437, que reúne os relatos de problema com QR Code. Pode ser loop de reconexão, cache ou rede (itens abaixo).

• Como checar: connect sem base64, log com erros de stream (código 515) ou timeout (408).
• Como corrigir: confira os itens 3 a 7, que são as causas apontadas na própria issue.

3. Instância presa depois de logout ou de erro 401

O PR 2560 relata que, depois de logout seguido de connect, o QR aparecia mas a conexão nunca completava, e só funcionava ao apagar e recriar a instância. O PR 2680 descreve instância que fica impossível de parear depois de um 401. Os dois estavam abertos na consulta.

• Como checar: a instância já foi conectada antes, caiu, e agora não volta.
• Como corrigir: apague a instância com DELETE /instance/delete e crie de novo com outro nome. Na mesma issue 2437, um usuário sugere também remover as conexões antigas no celular. Esse caminho vem do relato nos PRs, não de uma correção lançada. Se a instância está ligada ao Chatwoot, anote antes a configuração da integração, porque a instância nova precisa ser ligada de novo.

4. Imagem Docker antiga

A imagem mudou de dono: hoje é evoapicloud/evolution-api (o PR 1623 fez essa troca). Na issue 2224, de QR que o Android não lia, um usuário relatou que trocar a imagem antiga pela evoapicloud/evolution-api:v2.3.6 resolveu. Na issue 1511, outro relatou o mesmo ao atualizar para a 2.3.6.

• Como checar: veja a imagem na stack do Portainer. Se for atendai/evolution-api ou uma versão 2.2.x, está desatualizada.
• Como corrigir: troque para a imagem evoapicloud, numa versão estável listada nas releases oficiais, e faça backup do banco antes. Os dois casos acima são relatos de usuários nas issues.

5. A variável CONFIG_SESSION_PHONE_VERSION

É a dica mais repetida, e a que mais confunde. Ela fixa a versão do WhatsApp Web usada pela Baileys. Mas o CHANGELOG da 2.3.1 diz que a variável foi removida: desde então o código busca a versão sozinho. A documentação atual de variáveis não lista mais essa variável.

• Como checar: se você está na 2.2.x, ela ainda é lida. Na 2.3.1 em diante, em tese, não tem efeito.
• Como corrigir: na 2.2.x, usuários da issue 1014 e da 1511 resolveram atualizando o valor. Na 2.3.0, usuários da issue 1761 resolveram removendo a variável. Como o próprio CHANGELOG diz que a variável saiu na 2.3.1, nas versões novas ela não é o caminho: o que conta é a versão da imagem.

6. Redis e sincronização de histórico

A issue 2437 traz um contorno relatado por usuários, não uma correção oficial: desligar o cache Redis (CACHE_REDIS_ENABLED=false) e usar cache local (CACHE_LOCAL_ENABLED=true), e desligar o salvamento de chats, contatos, histórico e etiquetas (DATABASE_SAVE_DATA_*=false). A explicação dada é que a latência do Redis e a sincronização de histórico atrasam o pareamento. O CHANGELOG da 2.3.7 também cita correção de chaves do Redis que não eram apagadas no logout.

• Como checar: o QR some ou dá timeout justamente durante a sincronização inicial.
• O custo do contorno: com o salvamento desligado, menos coisa chega ao Chatwoot, porque chats, contatos e histórico deixam de ser gravados.

7. Rede, DNS e proxy

Na issue 2378, usuários relatam ter resolvido timeout configurando DNS na stack Docker, e na 2437 há relatos com a ordem de resolução IPv4/IPv6 (NODE_OPTIONS=--dns-result-order=ipv4first, e outros com ipv6first). Para proxy, o .env.example traz PROXY_HOST, PROXY_PORT, PROXY_PROTOCOL, PROXY_USERNAME e PROXY_PASSWORD como proxy global. Um usuário lembra que proxy na mesma VPS sai pelo mesmo IP e que proxy gratuito pode estar em lista de bloqueio.

• Como checar: o log mostra timeout (408) ou falha de conexão com os servidores do WhatsApp. Os ajustes acima são relatos de usuários, então teste um por vez para saber qual fez diferença.

8. Limite de QR e de aparelhos

A variável QRCODE_LIMIT (padrão 30) é a quantidade máxima de QR gerados, não um tempo. Ao chegar no limite, a Evolution encerra a tentativa e pede novo login. Se você deixou a tela aberta muito tempo, chame o connect de novo.

E o celular tem limite. A FAQ do WhatsApp sobre dispositivos conectados diz que dá para conectar o celular principal a até quatro dispositivos, e que eles desconectam se o celular ficar inativo por mais de 14 dias. Se o número já tem quatro aparelhos, remova um em Dispositivos conectados.

Evolution API desconectando depois de conectada

Se conecta e cai, olhe dois pontos. O aparelho principal ficou mais de 14 dias sem abrir o WhatsApp, o que desconecta os vinculados. Ou a instância recebeu um 401 (aparelho removido), caso da issue 2198: aí não adianta reconectar, precisa apagar e ler o QR de novo.

O lado honesto

A Evolution API é não oficial. Quando o WhatsApp muda o pareamento, como em julho de 2026, todo mundo que depende da Baileys fica esperando a correção, e isso pode levar semanas. Também existe risco de bloqueio do número.

Duas saídas. Trocar de biblioteca: a Evolution Go usa a whatsmeow, em Go, e eu mostro a instalação no vídeo acima e em Evolution Go com Chatwoot; a comparação com a WAHA está em WAHA ou Evolution API. Ou ir para a API oficial, que não quebra com mudança do WhatsApp Web; veja se a API oficial do WhatsApp vale a pena no seu caso.

A minha recomendação hoje: migrar para a AstraCalls

Eu já passei por esses problemas de QR Code com a Evolution e resolvi, mas a minha recomendação hoje, para quem está cansado de apagar instância, é migrar para a AstraCalls, a API que nós mantemos na Astra Online. Na minha experiência, ela é bem mais estável.

O que está no README oficial do projeto:

• API em Go sobre a whatsmeow, a mesma biblioteca da Evolution Go, e não sobre a Baileys;
• licença AGPL-3.0, com o código aberto no GitHub;
• pareamento por QR code, por código de pareamento ou por passkey;
• várias contas pareadas lado a lado;
• mensagens com botões, listas, carrossel e enquete;
• chamadas de voz e vídeo pelo WhatsApp;
• integração com o Chatwoot e node para n8n (pacote n8n-nodes-astracalls);
• deploy em Docker Swarm com Traefik, no mesmo formato dos tutoriais do canal.

Um ponto não muda: a AstraCalls também é uma API não oficial, então o risco de bloqueio do número pelo WhatsApp é o mesmo da Evolution. As ligações dentro do atendimento eu mostro em ligações do WhatsApp no Chatwoot.

Perguntas frequentes

Por que a Evolution API não gera QR Code?

As causas mais registradas no GitHub oficial são imagem desatualizada, instância presa depois de logout, cache e sincronização atrasando a conexão e mudanças do WhatsApp que a Baileys ainda não acompanhou.

A Evolution API conecta o QR mas não completa. O que fazer?

Se começou depois de julho de 2026, é provável que seja a mudança de pareamento descrita no PR 2727. Acompanhe o PR e a próxima release. Se a instância já tinha caído antes, os PRs 2560 e 2680 relatam que só apagar e recriar resolveu.

Ainda preciso da variável CONFIG_SESSION_PHONE_VERSION?

Desde a 2.3.1, o CHANGELOG diz que ela foi removida e a versão é buscada sozinha. Ela só tem efeito em versões antigas.

Por que a Evolution API fica desconectando?

Celular principal inativo por mais de 14 dias, aparelho removido (erro 401) ou instabilidade de rede. No caso do 401, apague a instância e conecte de novo.

Cansou de apagar instância?

O AstraChat, o Chatwoot Pro da Astra Online, tem uma tela de conexões que trabalha com APIs não oficiais e com a API oficial, no mesmo lugar onde a equipe atende, com Kanban, agentes de IA e disparador. Roda no seu servidor e sem cobrança por atendente.

Ele vem na Comunidade Astra Online, com código-fonte, atualizações, grupo VIP e a primeira instalação feita pelo especialista em Chatwoot Raphael Popiolek. Se a sua Evolution parou de conectar, me chame no WhatsApp com a versão da imagem e o trecho do log: com isso dá para ver em qual item do checklist você está.