QR Code não aparece
Resumo: Você clicou em "Gerar QR Code" mas a tela fica em branco, com spinner infinito, ou aparece erro. Geralmente é problema momentâneo do worker. Tente recarregar; se persistir, recrie o canal.
Quando usar isso
Após clicar em Gerar QR Code durante a conexão Baileys:
- A tela mostra spinner por mais de 30 segundos sem QR aparecer.
- Aparece mensagem de erro "Falha ao gerar QR Code".
- O QR aparece mas trava (não atualiza, e o WhatsApp do celular fala "código expirado").
Causas comuns e o que fazer
Worker ainda está inicializando
O que acontece: O componente que cria a sessão Baileys e gera o QR (chamado Worker internamente) pode levar 6 a 15 segundos para responder ao primeiro QR. É normal.
O que fazer:
- Espere 30 segundos antes de assumir erro.
- O painel mostra um spinner enquanto aguarda.
O QR está expirando rápido demais
O que acontece: O QR é regenerado a cada poucos segundos pelo Baileys. Se a renderização no navegador está lenta (rede ruim), ele pode parecer "trocando o tempo todo".
O que fazer:
- Recarregue a página.
- Em um ambiente com internet boa, o QR fica estável por tempo suficiente para escanear.
Sessão antiga ainda está sendo limpa
O que acontece: Se você tentou conectar antes e o canal "ficou pelo caminho" (status PENDING_QR ou FAILED), o worker pode estar tentando reutilizar uma sessão antiga corrompida.
O que fazer:
- Vá para a lista de canais.
- Remova o canal incompleto (botão "Remover").
- Crie um novo canal Baileys do zero.
- Aguarde o QR aparecer.
Worker está fora do ar
O que acontece: Em ambientes de produção, se o worker (que fica em servidor separado) estiver com problema, o QR não é gerado.
O que fazer:
- Verifique o status do gateway na página de status do seu fornecedor.
- Aguarde alguns minutos — em geral, problemas no worker se resolvem rapidamente.
- Se persistir mais de 10 minutos, contate o suporte.
Limites de canais atingidos
O que acontece: Se a sua conta atingiu o limite máximo de canais simultâneos (configurado no seu plano), o gateway pode recusar a criação de novos.
O que aparece: Erro CHANNEL_LIMIT_REACHED ou similar antes mesmo do QR aparecer.
O que fazer:
- Remova canais antigos não utilizados.
- Ou faça upgrade do plano.
Bloqueio temporário do número pelo WhatsApp
O que acontece: O WhatsApp tem proteção: se um mesmo número tentar conectar como aparelho secundário muitas vezes seguidas (5+ falhas em 1 hora, por exemplo), a Meta bloqueia novas tentativas por algumas horas.
O que fazer:
- Aguarde 1-2 horas antes de tentar novamente.
- Confirme que o celular está com WhatsApp logado e funcionando normalmente.
Mensagens de erro que você pode ver
| Mensagem | Significado |
|---|---|
Failed to generate QR | Worker não conseguiu inicializar a sessão Baileys |
Session already exists | Tem outra sessão pendente para esse canal |
Worker unavailable | Componente de processamento offline |
Channel limit reached | Plano atingiu limite de canais |
PENDING_QR timeout | Esperou muito tempo sem nada gerar |
Passos para resolver (em ordem)
- Aguarde 30 segundos. A maioria das vezes é só inicialização.
- Recarregue a página. Resolve casos onde o navegador perdeu a conexão com o gateway.
- Verifique outros canais. Se outros canais Baileys também estão dando o mesmo problema, é problema do worker — aguarde ou contate suporte.
- Remova e recrie. Se persistir, apague o canal incompleto e crie um novo.
- Tente código de pareamento. Como alternativa, use conexão por pairing code.
- Aguarde 1-2h. Se nada funciona, pode ser bloqueio temporário Meta. Espere e tente depois.
- Contate suporte. Tenha em mãos o ID da conta e o nome/ID do canal que está tentando criar.
Dúvidas comuns
A primeira tentativa demorou e o QR apareceu, mas o WhatsApp diz "código inválido". O QR já estava expirado quando você escaneou. Gere um novo (sai automático após alguns segundos).
O QR aparece, eu escaneio, mas o canal continua em PENDING_QR. O scan pode não ter chegado ao gateway. Espere mais 10 segundos. Se continuar pendente, gere QR novo e escaneie outra vez.
Outro Baileys da mesma conta gerou QR normalmente. Por que este não? Pode ser problema específico daquele número (sessão antiga pendente, bloqueio Meta temporário). Tente recriar.
O QR funciona em desenvolvimento, não em produção. Verifique se as variáveis de ambiente (WORKER_URL, REDIS_URL) estão corretas no ambiente de produção. Pode ser problema de configuração, não do QR em si.