WAHA fora do ar
O provedor das sessões (WAHA), o gateway ou o Redis caíram — o que para, o que se recupera sozinho e o que conferir na volta.
Sintomas
| Quem caiu | Sinais |
|---|---|
| WAHA | healthcheck unhealthy no compose; workers logando challenge refresh failed e reconnect restart failed; iniciar pareamento falha com waha POST /api/sessions -> …; nenhum session.status chegando |
waha-db | o WAHA não sobe (depende dele service_healthy) |
| gateway | WAHA não consegue entregar webhooks; GET /health do gateway sem resposta |
| Redis | GET /health da api e do gateway em 503 (degraded); workers logando provider stream read failed e, num reinício, abortando com redis unreachable, aborting boot |
Confirmar
docker compose ps waha waha-db gateway workers redis
docker compose logs --tail 200 waha
docker compose exec waha curl -fsS -H "X-Api-Key: <WAHA_API_KEY>" http://localhost:3000/health
curl -s https://api.superdinda.com/healthO que se recupera sozinho
- Sessões: ficam no
waha-db. ComWHATSAPP_RESTART_ALL_SESSIONS: "true"o WAHA reabre todas ao subir, sem novo vínculo. - Webhooks: cada sessão foi criada com retry exponencial (2 s, 10 tentativas). Gateway fora por pouco tempo não perde eventos.
- Fila: o gateway grava em
provider:waha(Redis com--appendonly yes, até ~50 000 entradas) e os workers leem pelo consumer group. Eventos que chegaram antes de os workers voltarem são lidos na volta. - Estado: ao voltar, o WAHA manda
session.status;WORKINGnum pareamentodegradedo leva de volta apaired, sem notificar de novo.
O que não se recupera sozinho
Em aberto
Durante a queda do WAHA, o tick de reconexão incrementa a tentativa e zera
next_retry_at antes de chamar o restart. Se o restart falha (WAHA
fora), nada agenda outro: o pareamento fica degraded parado até um
session.status novo chegar.
Em aberto
Webhooks que esgotarem as 10 tentativas se perdem, e não há reconciliação com
o estado do WAHA (state() não é chamado por ninguém). Entradas cujo handler
falhou ficam pendentes no Redis e não são relidas sozinhas.
Passos
- Suba o que caiu, na ordem das dependências:
redisewaha-db, depoiswaha, depoisgatewayeworkers. Em produção, pelo Dokploy (compose do backend). - Se o WAHA não sobe, veja os logs. Em produção,
WAHA_IMAGE_TAG,WAHA_API_KEY,WAHA_POSTGRES_PASSWORDeWAHA_DASHBOARD_*são obrigatórios (${VAR:?}): faltando um, o deploy falha nomeando a variável. - Se a queda veio de uma troca de imagem, volte a tag anterior (Atualizar o WAHA).
- Na volta, abra Clientes → Conexões filtrando
degraded. Para cada um parado (semnext_retry_ate sem evento novo na linha do tempo), confira a sessão no WAHA (GET /api/sessions/sd-<pairingUid>): se estáWORKINGe o pareamento não voltou, ou se não existe mais, use o reset da vaga e peça novo pareamento (Sessão caiu). - Olhe as entradas pendentes:
redis-cli XPENDING provider:waha workers.
Outros provedores
- IPRoyal (API): só as telas de Compras/Orçamento param (catálogo, cotação, saldo). A alocação lê o pool do nosso banco e continua funcionando; os endereços em si não dependem da API.
- Meta (WhatsApp Business): afeta o envio do link de consentimento, não as
sessões.
bun run wa:doctordiagnostica número, templates e assinatura do webhook.
Quando escalar
- WAHA fora com famílias pareadas: acompanhe Conexões até todos os
degradedvoltarem apairedou serem tratados. - Falha que se repete após subir de novo → abra um problema no vault com logs.
Fontes
backend/docker-compose.prod.yml,backend/docker-compose.ymlbackend/apps/gateway/main.ts,backend/apps/workers/{main,consume-provider-events,reconnect-ticker,challenge-refresher}.tsbackend/src/domains/channels/use-cases/{apply-provider-state,start-pairing}.ts,adapters/waha-adapter.tsbackend/src/infra/{streams,provider-stream}.ts,backend/src/http/routes/system/health.route.tsbackend/src/domains/proxies/use-cases/{allocate,supply}.ts,backend/scripts/wa-doctor.ts- Vault: AD-002, AD-010, AD-012,
problems/2026-09-11-waha-dashboard-loop-basic-auth