Quando Jobs do Cron Nao Executam - Checklist de Troubleshooting

2026-06-05 Tempo de leitura: Cerca de 11 min Dificuldade: Intermediario

O que voce vai aprender

• Por que um script que funciona manualmente falha no cron
• Como confirmar falhas do cron pelos logs
• Como resolver as armadilhas comuns: PATH, ambiente, sintaxe de agendamento e permissoes

Por que funciona manualmente mas nao no cron?

Conclusao: Diferente de um login interativo, o cron executa um shell nao-interativo que nunca le .bashrc / .profile e mantem um PATH minimo. Essa diferenca de ambiente explica a maioria dos casos de "funciona manualmente, falha no cron".

Uma execucao manual (shell de login) e uma execucao no cron iniciam o shell por caminhos fundamentalmente diferentes.

Uma vez que voce internalize essa diferenca, cada verificacao abaixo se torna "preencher o que falta no ambiente minimo do cron", um item por vez.

O daemon do cron esta rodando?

Conclusao: Primeiro confirme o daemon com systemctl status cron. Se esta parado, nenhum job executa. Esta e a pre-condicao a descartar antes de qualquer outra coisa.

# Ubuntu / Debian
$ systemctl status cron

# RHEL / CentOS
$ systemctl status crond

Se nao esta active (running), habilite e inicie.

$ sudo systemctl enable --now cron

Como confirmar se executou pelos logs?

Conclusao: O cron registra no syslog toda vez que dispara. Se grep CRON /var/log/syslog nao mostra entrada, o job nunca foi iniciado.

A existencia ou nao de uma linha de log muda a direcao da sua triagem.

# Ubuntu / Debian
$ grep CRON /var/log/syslog | tail -20

# Via journal do systemd
$ journalctl -u cron --since "1 hour ago"

# RHEL / CentOS
$ sudo grep CRON /var/log/cron | tail -20

Um disparo bem-sucedido deixa uma linha como esta.

Jun  5 10:00:01 host CRON[12345]: (alice) CMD (/home/alice/backup.sh)

Como ler:

• Existe uma entrada -> o cron disparou. O problema esta no script (PATH / permissoes / ambiente). Prossiga para as proximas secoes.
• Sem entrada -> nunca foi iniciado. Suspeite de erro na sintaxe de agendamento, localizacao errada do crontab ou daemon parado.

Por que o PATH causa falha?

Conclusao: O PATH do cron e minimo (frequentemente /usr/bin:/bin). Escreva comandos em /usr/local/bin e similares com caminhos absolutos, ou defina PATH no topo do crontab.

"Funciona manualmente mas command not found no cron" quase sempre vem disso. Ha tres correcoes.

# 1) Usar caminho absoluto (encontrar com which)
$ which node
/usr/local/bin/node

# No crontab, especificar o caminho absoluto
* * * * * /usr/local/bin/node /home/alice/job.js

# 2) Definir PATH no topo do crontab
PATH=/usr/local/bin:/usr/bin:/bin
0 * * * * node /home/alice/job.js

# 3) Exportar PATH dentro do script antes de executar
#!/bin/bash
export PATH=/usr/local/bin:/usr/bin:/bin
node /home/alice/job.js

* * * * * env > /tmp/cronenv 2>&1

$ diff <(env) /tmp/cronenv

Uma variavel de ambiente ausente e a causa?

Conclusao: O cron nao le .bashrc / .profile. Jobs frequentemente falham porque LANG ou variaveis de runtime (NODE_ENV, JAVA_HOME, etc.) nao estao definidas.

Variaveis que seu shell interativo definiu implicitamente estao vazias no cron. Defini-las explicitamente no script e a correcao mais confiavel.

#!/bin/bash
# Variaveis que tendem a nao estar definidas no ambiente do cron
export LANG=en_US.UTF-8
export HOME=/home/alice
export NODE_ENV=production

cd "$HOME/app" || exit 1
/usr/local/bin/node index.js

Como encontrar erros de agendamento e sintaxe?

Conclusao: Sao cinco campos: minuto, hora, dia-do-mes, mes, dia-da-semana. O comportamento OR de dia/dia-da-semana e o % sem escape sao as armadilhas classicas. Se nenhuma entrada de execucao aparece no log, suspeite da sintaxe primeiro.

+-- minuto (0-59)
| +-- hora (0-23)
| | +-- dia do mes (1-31)
| | | +-- mes (1-12)
| | | | +-- dia da semana (0-7, 0 e 7 sao domingo)
| | | | |
* * * * *  comando a executar

Tropecos comuns:

• % nao e literal: o cron transforma % em um comando em nova linha. Faca escape com barra invertida, ex. escreva date +%Y-%m-%d como date +\%Y-\%m-\%d.
• Dia e dia-da-semana ambos definidos: 0 0 1 * 1 executa no "dia 1 ou segunda-feira" (um OR), nao no "dia 1 e segunda-feira". Isso facilmente diverge da intencao.
• Sem comentarios no final da linha: * * * * * cmd # nota e invalido. Comentarios devem estar em sua propria linha com #.

Verificar permissoes e localizacao do crontab

Conclusao: Um script sem permissao de execucao ou com caminho de shebang errado falha logo apos disparar. Ao colocar arquivos em /etc/cron.d/, e facil esquecer que a linha precisa de um campo de usuario.

Permissao de execucao do script e shebang

$ chmod +x /home/alice/backup.sh
$ head -1 /home/alice/backup.sh
#!/bin/bash

Um script editado no Windows pode pegar finais de linha CRLF e falhar com bad interpreter. Veja Corrigindo "bad interpreter" para detalhes.

A sintaxe difere por tipo de crontab

# /etc/cron.d/ e /etc/crontab exigem um campo de usuario
# +min +hr +dia +mes +dsem +usuario   +comando
  0    3   *    *    *     alice      /home/alice/backup.sh

Errar o campo de usuario e o log mostra um erro como bad username, ou o job silenciosamente nunca executa.

Como redirecionar saida para depuracao?

Conclusao: O cron envia saida padrao e erro padrao por email. Em hosts sem MTA, essa saida desaparece, entao redirecionar para arquivo torna os erros visiveis.

# Enviar stdout e stderr para um arquivo de log
* * * * * /home/alice/backup.sh >> /tmp/backup.log 2>&1

2>&1 combina erro padrao no mesmo arquivo. Apos executar, /tmp/backup.log mantem as mensagens brutas de command not found ou Permission denied.

* * * * * date >> /tmp/cron-test.log 2>&1