# runner debug last-error

Lê /opt/runner/logs/deploy-events.jsonl, encontra o registro de falha de deploy mais recente para a app e o exibe: versão tentada, timestamp e mensagem completa de erro. Disponível desde v2.30.1 (Issue #16).

Use quando: runner fetch --deploy terminou com falha e as últimas linhas do output mostraram "Run: runner debug last-error " como próximo passo.

# Sintaxe

runner debug last-error [OPTIONS] <APP>

# Flags

# Logs do container falho (v2.50.0+)

Em falha de start/health, o rollback remove o container — os logs dele são arquivados antes em <logs_dir>/failures/<app>/<version>_<timestamp>.log e a mensagem de erro do deploy inclui o caminho. Use esse arquivo (não o docker logs do container vivo, que é o da versão que voltou no rollback).

Quando a falha acontece antes de o container existir, por exemplo na pré-checagem de volumes, não há log de container para arquivar, e nenhum arquivo é gravado (v2.153.1+). A causa fica no campo cause do evento. Antes disso o Runner gravava ali a resposta de erro do Docker (No such container), como se fosse log da aplicação.

# Causa e fase (v2.153.1+)

Uma falha de deploy costuma chegar com um resumo genérico, como container could not start, e a causa real por baixo dele. Até a v2.153.0 só o resumo era gravado. Desde a v2.153.1 o evento guarda também:

A saída humana mostra Causa e Fase abaixo do erro, e os próximos passos são escolhidos pela causa. Duas categorias foram acrescentadas:

Eventos gravados antes da v2.153.1 não têm cause nem phase: para eles, só o resumo existe.

# Exemplo

$ runner debug last-error meu-app
Last DeployFailure for meu-app:

  │  version    v1.4.2
  │  timestamp  2026-05-27T14:32:11Z
  │  error      healthcheck failed after 3 retries (GET /health → 502 Bad Gateway)
  │             container exited with code 1 during startup
  │             see: docker logs meu-app-v1.4.2-blue

Output JSON:

$ runner debug last-error meu-app --json

{
  "app": "meu-app",
  "version": "v1.4.2",
  "timestamp": "2026-05-27T14:32:11Z",
  "error": "healthcheck failed after 3 retries (GET /health → 502 Bad Gateway)\ncontainer exited with code 1 during startup\nsee: docker logs meu-app-v1.4.2-blue",
  "event": "DeployFailure"
}

# Como o runner expõe este comando

Durante fetch --deploy, quando um deploy falha, o runner imprime na saída:

Deploy FAILED for meu-app v1.4.2.
Next steps:
  runner debug last-error meu-app   # ver erro completo
  runner rollback meu-app           # voltar para versão anterior

O comando debug last-error é o subcomando last-error dentro do grupo debug, não um comando de nível superior chamado debug-last-error.

# Arquivo de log subjacente

O runner grava cada evento de deploy (sucesso e falha) em:

/opt/runner/logs/deploy-events.jsonl

debug last-error faz tail nesse arquivo e retorna o registro mais recente com "event": "DeployFailure" para a app solicitada. Para inspecionar o histórico completo manualmente:

grep '"app":"meu-app"' /opt/runner/logs/deploy-events.jsonl \
  | jq 'select(.event == "DeployFailure")'

# Quando não há falha registrada

$ runner debug last-error meu-app
No DeployFailure found for meu-app.

Isso indica que a app nunca falhou um deploy neste servidor, ou que o log foi rotacionado. Verifique com runner status meu-app se o estado atual é esperado.

# Erros comuns

• app_not_found — app não registrada neste servidor; verifique com runner list.
• log_not_found — /opt/runner/logs/deploy-events.jsonl ausente (runner antigo ou instalação limpa); nenhum deploy foi executado ainda neste servidor.

# O outro subcomando do grupo: `debug test`

runner debug test [-a <app>] [--include-sensitive]

Executa todos os comandos read-only com --json e captura a saída como amostra. Existe para integradores do CCS Client entenderem a superfície de dados completa do runner sem ter que descobrir comando a comando.

Por ser read-only, é seguro rodar em produção.

# Veja também

• `runner rollback` — reverter para a versão anterior após falha
• `runner logs` — logs do container em execução
• `runner status` — estado atual da app
• `runner fetch` — ciclo de fetch e deploy automático