# Healthcheck failed

Sintoma:

[FAIL] meu-app  Phase 1.4: failed health check after 30s

Ou no modo HTTP:

[FAIL] meu-app  /health returned 502 after 30s (3/3 retries)

# Causa

O container do deploy novo subiu, mas a probe configurada no manifest (http/tcp/cmd) não retornou OK no prazo definido. O Runner é blue-green: ele mantém o container antigo servindo tráfego até o novo passar no health. Por isso, healthcheck failed = rollback automático, seu site continua no ar.

# Diagnóstico

runner status meu-app             # container state atual (running/stopped)
runner logs tail meu-app          # logs do container que falhou
runner debug last-error meu-app   # último DeployFailure estruturado
runner health meu-app             # roda a probe manualmente uma vez

Olha primeiro o debug last-error — ele já vem com a mensagem de erro e fix sugerido.

# Fix — cenário 1: timeout muito curto

Se a app demora 40s pra subir mas o healthcheck tem timeout 30s:

# .deploy.yml
healthcheck:
  mode: http
  path: /health
  timeout: 60s   # default 30s
  retries: 3

Commit + push na branch dist → próximo fetch --deploy aplica.

# Fix — cenário 2: app demora pra bootar (migrations, cache warm)

Use start_period pra ignorar falhas durante o boot:

healthcheck:
  mode: http
  path: /health
  start_period: 60s   # ignora primeiros 60s

# Fix — cenário 3: endpoint errado ou modo errado

Confirme que a app expõe /health:

docker exec -it $(docker ps -q --filter name=meu-app) curl localhost:8080/health

Se não expõe, mude pra mode: tcp (TCP connect) ou crie o endpoint. Veja Healthcheck modes.

# Fix — cenário 4: app realmente não sobe (crash loop)

runner logs history meu-app   # ver logs do último container parado

Se for bug de código: corrige + push. Se for env var faltando: veja Secrets lifecycle.

# Como prevenir

• Teste localmente com docker build && docker run antes de push.
• Configure start_period se a app tem migrations no boot.
• Use mode: tcp se HTTP é overkill — a probe TCP é mais leve.
• Configure notificações (Notificações) para ser avisado de fails sem precisar checar manualmente.

# Conceito relacionado

Por que o site continuou no ar? Veja GitOps mode — o Runner não substitui o container até o health passar.