Exit code 1 vs exit code 2: o que a diferença significa
Exit 1 significa "algo falhou", ponto final. Exit 2 convencionalmente significa "você me usou errado" - argumentos ou sintaxe ruins - mas muitas ferramentas dobram a regra.
Tanto 1 quanto 2 são falhas comuns diferentes de zero, mas apontam causas raiz distintas. Conhecer a convenção frouxa direciona sua depuração mais rápido para o lugar certo.
Exit code 1: falha genérica
Por convenção, 1 é o código coringa "a operação falhou". Um teste que falhou, um erro de build, uma assertion, um grep sem correspondência não vazio - quase toda ferramenta recorre a 1 quando algo deu errado mas não há um código mais específico a usar.
Exit code 2: uso incorreto / erro de uso
Muitos programas e o próprio shell usam 2 para "você me invocou incorretamente" - uma flag desconhecida, um argumento obrigatório faltando ou um erro de sintaxe. O Bash retorna 2 para erros de sintaxe de shell; ferramentas como grep usam 2 especificamente para um *erro* (arquivo ruim, regex ruim) em oposição a 1 para "nenhuma correspondência".
Por que a regra é frouxa
Não há padrão imposto acima de 0. Muitas ferramentas (make, pytest, linters) definem seus próprios significados para 1 e 2, então a convenção é uma dica, não uma garantia. Sempre confirme contra os exit codes documentados da ferramenta específica.
Como agir sobre isso no CI
- Exit 1 → leia os logs; é uma falha real, não um problema de uso.
- Exit 2 → suspeite de uma flag ruim, argumento faltando ou erro de sintaxe no comando.
- Na dúvida, confira a documentação da ferramenta - 1 e 2 são definidos pela ferramenta acima da convenção.
Principais conclusões
- Exit 1 é o código genérico de "falhou" usado por quase tudo.
- Exit 2 convencionalmente significa uso incorreto: argumentos ruins ou erros de sintaxe.
- A convenção é frouxa - muitas ferramentas redefinem 1 e 2 para si mesmas.
- No CI, exit 2 deve fazer você reler o comando, não só a saída.