Resolvendo "invalid cron expression" e erros comuns de sintaxe Cron: Guia Completo

O Cron é a ferramenta padrão para agendar tarefas repetitivas em sistemas operacionais do tipo Unix. Quer você esteja executando um backup de banco de dados todas as noites ou enviando uma newsletter toda segunda-feira, o Cron é o motor nos bastidores. No entanto, sua sintaxe de "cinco campos" (ou seis campos) pode ser confusa, levando a erros como invalid cron expression (expressão cron inválida), cron syntax error (erro de sintaxe cron) ou o mais frustrante: cron job not running (o trabalho cron não está sendo executado).

Neste guia, vamos detalhar a sintaxe do Cron e mostrar como corrigir os erros de agendamento mais comuns.

1. Mensagens de Erro Comuns do Cron

Ao contrário de um compilador, o Cron nem sempre fornece uma mensagem de erro clara. Em vez disso, você pode ver:

Validação do Crontab: crontab: installing new crontab seguido por errors in crontab file, can't install (erros no arquivo crontab, não é possível instalar).
Logs do Sistema: ORPHAN (no passwd entry) ou CMD (failed to execute).
Bibliotecas de Análise: invalid cron expression, Unexpected end of expression ou Number out of range (número fora do intervalo).

2. Principais Causas e Soluções

2.1 A Confusão entre "5 vs 6 Campos"

O Cron padrão do Linux (Vixie) utiliza 5 campos: Minuto Hora Dia Mês Dia-da-semana

No entanto, muitas bibliotecas modernas (como Quartz em Java ou Node-Cron) e alguns sistemas (como AWS Lambda ou Spring) utilizam 6 campos, adicionando Segundos no início ou o Ano no final.

O Erro: Usar uma expressão de 6 campos em um crontab padrão do Linux.

A Solução: Verifique a documentação do seu ambiente. Se você estiver usando crontab -e no Linux, use 5 campos. Se estiver usando uma biblioteca específica, verifique se ela espera segundos.

2.2 Erros de Intervalo e Passo

O Cron utiliza / para passos (ex: */5 para cada 5 unidades) e - para intervalos. Um erro comum é usar um número fora do intervalo permitido.

O Erro:

* * 31 2 * (Tentando executar em 31 de fevereiro)
60 * * * * (O minuto 60 é inválido; use 0-59)
* 24 * * * (A hora 24 é inválida; use 0-23)

A Solução: Certifique-se sempre de que seus números estejam dentro destes limites:

Minutos: 0-59
Horas: 0-23
Dia do mês: 1-31
Mês: 1-12 (ou JAN-DEC)
Dia da semana: 0-6 (0 é domingo, ou SUN-SAT)

2.3 A Armadilha do "Dia do Mês" vs "Dia da Semana"

No Cron padrão, se você especificar tanto um "Dia do Mês" quanto um "Dia da Semana", a tarefa será executada quando qualquer uma das condições for atendida (lógica OR), não ambas (lógica AND).

O Erro: 0 0 1 * 1 (Você espera que ele execute apenas se o dia 1 do mês for uma segunda-feira, mas ele na verdade executará todo dia 1 do mês E toda segunda-feira).

A Solução: Para obter a lógica "AND", você deve usar uma verificação por comando: 0 0 1 * * [ "$(date +\%u)" = "1" ] && /path/to/command

2.4 Variáveis de Ambiente e Caminhos

Uma razão muito comum para o "cron não estar funcionando" é que o Cron executa comandos em um ambiente muito minimalista. Seu PATH pode ser diferente e seu .bashrc não é carregado.

O Sintoma: O comando funciona quando você o executa manualmente, mas falha no Cron.

A Solução: Sempre use caminhos absolutos tanto para o comando quanto para quaisquer arquivos que ele acesse: /usr/bin/python3 /home/usuario/script.py >> /home/usuario/cron.log 2>&1

3. Solução de Problemas Avançada

3.1 Sinais de Porcentagem (%) no Crontab

Em um arquivo crontab, o sinal de porcentagem % tem um significado especial (representa uma nova linha). Se o seu comando contiver um % (comum em comandos date), você deve escapá-lo com uma barra invertida \%.

O Erro: 0 0 * * * tar -cvf backup-$(date +%Y-%m-%d).tar /data

La Solución: 0 0 * * * tar -cvf backup-$(date +\%Y-\%m-\%d).tar /data

3.2 Redirecionamento de Saída

Se um trabalho do Cron falhar silenciosamente, geralmente é porque a saída (stdout/stderr) está sendo enviada para um arquivo de e-mail local que você nunca verifica. Solução: Sempre redirecione a saída para um arquivo de log para ver o que deu errado: >> /var/log/meu_trabalho.log 2>&1.

4. Prevenção e Melhores Práticas

Use um Analisador/Gerador: Não adivinhe. Use uma ferramenta visual para ver exatamente quando sua expressão será executada.
Comente seus Trabalhos: Sempre adicione um comentário acima da sua entrada de crontab explicando o que ela faz.
Use Caminhos Absolutos: Não podemos enfatizar isso o suficiente. /usr/local/bin/node em vez de node.
Teste com "A Cada Minuto": Ao configurar um trabalho pela primeira vez, ajuste-o para * * * * * para verificar se funciona, e depois mude para o agendamento real.

5. FAQ: Perguntas Frequentes

P: O 0 ou o 7 representam o domingo?

R: Na maioria das implementações de Cron (como Linux), tanto o 0 quanto o 7 representam o domingo. No entanto, algumas usam estritamente o 0. Usar SUN costuma ser mais claro.

P: Como executo uma tarefa a cada 5 minutos?

R: Use a sintaxe de passo: */5 * * * *.

P: Por que meu trabalho Cron não funcionou às 2h da manhã durante o horário de verão?

R: Este é um problema clássico. Quando o relógio adianta ou atrasa, os trabalhos agendados durante essa hora podem ser executados duas vezes ou não serem executados. Solução: Evite agendar tarefas críticas entre 1h e 3h da manhã, ou configure seu servidor para o horário UTC.

6. Ferramenta de Verificação Rápida

Confuso com os asteriscos e barras? Use nosso Analisador e Visualizador de Expressões Cron. Ele pode:

Traduzir instantaneamente a sintaxe Cron para uma linguagem humana compreensível.
Calcular os próximos 5 horários de execução.
Suportar formatos de 5 e 6 campos.
Validar sua expressão e destacar erros de sintaxis.

Erros Relacionados

Resolvendo erros 'Unexpected token in JSON'
Como corrigir erros de 'invalid base64 string'
Entendendo os erros de indentação em YAML

Resolvendo 'invalid cron expression' e erros comuns de sintaxe Cron