Magento 2: cron mal configurado silencia falhas, trava indexação e quebra pedidos — como diagnosticar

Por que o cron é crítico no Magento 2

O cron é o coração assíncrono do Magento 2. Diferente de um simples agendador de tarefas, o Magento implementa seu próprio sistema de fila sobre o cron do sistema operacional — toda vez que o cron do SO executa bin/magento cron:run, o Magento processa as tarefas que estão na fila interna (cron_schedule), respeitando intervalos e grupos configurados em XML.

Quando o cron para — seja por má configuração, por hospedagem que mata processos, por um usuário errado no crontab ou por erro silencioso — as consequências aparecem em cascata:

• Indexação desatualizada: produtos com estoque zerado ainda aparecem como disponíveis, preços de regras de promoção não são calculados
• Emails represados: confirmações de pedido, notificações de envio e senhas de recuperação ficam na fila sem sair
• Order status travado: atualizações de status automáticas (pending → processing → complete) dependem de cron jobs de cada módulo
• Cache não renovado: invalidação programada de cache de bloco e de full page não ocorre
• Sessões acumulando: sem a limpeza periódica, a tabela session (ou os arquivos em var/session) crescem indefinidamente
• Cotações expiradas: carrinhos abandonados não são limpos, a tabela quote incha

O pior aspecto: nada disso gera um erro visível imediato. A loja funciona, os clientes conseguem comprar — mas os processos de back-office vão silenciosamente acumulando atraso.

Como verificar se o cron está rodando

O Magento 2 oferece um comando nativo para verificar o estado da fila de cron:

php bin/magento cron:status

O output mostra grupos de cron e quantas tarefas estão em cada estado: pending, running, success, failed, missed. O problema é que esse comando reporta o estado atual da fila, não se o cron do SO está ativo.

Para confirmar se o processo está realmente sendo disparado, verifique diretamente:

# Verificar processos cron ativos
ps aux | grep cron

# Ver log do cron do sistema (Linux/Ubuntu)
tail -f /var/log/cron.log
# ou em sistemas com journalctl:
journalctl -u cron -n 50

# Verificar o crontab do usuário da aplicação (ex: www-data)
crontab -l -u www-data

Outro indicador confiável é consultar a tabela diretamente no banco de dados:

SELECT job_code, status, scheduled_at, executed_at, finished_at
FROM cron_schedule
WHERE scheduled_at > NOW() - INTERVAL 30 MINUTE
ORDER BY scheduled_at DESC
LIMIT 30;

Se todas as tarefas recentes estiverem com status pending e sem executed_at, o cron não está executando. Se a contagem de registros na tabela ultrapassar 1000–2000, é sinal de backlog acumulado — o cron pode estar rodando mas lento, ou pode ter parado e retomado sem limpar a fila antiga.

Os 3 sintomas mais comuns de cron quebrado

1. Índices com status REINDEX REQUIRED

Execute php bin/magento indexer:status e verifique se algum indexer está como invalid. Com o cron configurado para reindexação agendada (Update by Schedule), os indexers são reprocessados automaticamente pelo cron group index. Sem cron, qualquer alteração de produto, preço ou estoque fica pendente indefinidamente.

O impacto vai além da lentidão: um indexer de preço invalido significa que promoções não são aplicadas corretamente no frontend. Um indexer de estoque parado significa que produtos esgotados continuam aparecendo e gerando vendas que precisarão ser canceladas manualmente.

2. Emails represados na fila

O Magento 2 usa um sistema de fila de email gerenciado pelo cron. Os emails são escritos na tabela interna de queue e despachados em lotes pelo job sales_send_order_emails e similares. Quando o cron para, os emails simplesmente ficam parados — sem nenhum erro visível no admin.

Para verificar se há emails represados, acesse Admin → System → Action Logs → Bulk Actions ou consulte diretamente:

SELECT * FROM email_queue LIMIT 20;
-- ou em versões mais recentes:
SELECT * FROM queue_message WHERE topic_name LIKE 'email%' LIMIT 20;

3. Status de pedido não atualiza automaticamente

Fluxos automáticos de pedido como captura automática de pagamento, criação de faturas programadas e atualizações de status de envio integradas a transportadoras dependem de cron jobs específicos de cada módulo. Quando o cron para, pedidos ficam presos em pending ou processing indefinidamente, forçando intervenção manual — que escala mal.

Como configurar o cron corretamente

A configuração canônica do Magento 2 no crontab usa dois comandos distintos — um para gerar as tarefas e outro para executá-las:

* * * * * /usr/bin/php /var/www/html/magento/bin/magento cron:run >> /var/www/html/magento/var/log/cron.log 2>&1
* * * * * /usr/bin/php /var/www/html/magento/bin/magento cron:run --group index >> /var/www/html/magento/var/log/cron_index.log 2>&1

Pontos críticos na configuração:

• Usuário correto: o cron precisa rodar com o mesmo usuário que é dono dos arquivos da aplicação (geralmente www-data ou um usuário dedicado). Rodar como root pode criar arquivos de cache e lock com permissões incorretas que bloqueiam execuções subsequentes
• Caminhos absolutos: sempre use o caminho completo do PHP (/usr/bin/php ou /usr/local/bin/php8.2) e do bin/magento. Paths relativos falham silenciosamente no contexto do cron
• Versão correta do PHP: se o servidor tem múltiplas versões do PHP, certifique-se de usar a mesma versão que o Magento requer. Use php -v e /usr/bin/php -v para confirmar
• Redirecionamento de log: redirecione stdout e stderr para um arquivo de log. Sem isso, erros silenciosos são impossíveis de rastrear

Para verificar qual PHP está disponível e qual versão usar:

which php
php -v
ls /usr/bin/php*
# se houver múltiplas versões:
update-alternatives --list php

Cron groups no Magento 2

O Magento 2 organiza os jobs de cron em grupos configurados em crontab.xml. Cada grupo pode ter configurações independentes de paralelismo e timeout. Os três grupos nativos mais importantes são:

Módulos de terceiros frequentemente adicionam seus próprios grupos. Um módulo de marketplace pode ter um grupo marketplace que sincroniza pedidos com APIs externas — se apenas o grupo default estiver rodando, a sincronização para sem nenhum alerta.

Para listar todos os jobs configurados e seus grupos:

php bin/magento cron:install --dry-run
# ou diretamente no banco:
SELECT DISTINCT job_code, status, COUNT(*) as total
FROM cron_schedule
WHERE scheduled_at > NOW() - INTERVAL 1 HOUR
GROUP BY job_code, status
ORDER BY job_code;

Monitoramento contínuo

Verificar o cron manualmente é insuficiente em produção. O ideal é ter monitoramento automático que alerte antes que o problema se manifeste para clientes.

Verificação via script de saúde

Um script simples que pode ser executado por um cron de monitoramento externo (Nagios, Zabbix, UptimeRobot via webhook) ou até por um segundo servidor:

#!/bin/bash
# cron_health_check.sh
PENDING=$(mysql -u magento -pSENHA magento_db -se \
  "SELECT COUNT(*) FROM cron_schedule \
   WHERE status='pending' AND scheduled_at < NOW() - INTERVAL 10 MINUTE;")

if [ "$PENDING" -gt "100" ]; then
  echo "ALERTA: $PENDING tarefas cron pendentes há mais de 10 minutos"
  # envia alerta via curl, email ou webhook
fi

New Relic e APM

Se você usa New Relic, os cron jobs do Magento aparecem como transações do tipo CLI. Configure alertas para quando a frequência de execução do cron:run cair abaixo do esperado (menos de 1 execução por minuto indica problema). O New Relic também captura exceções PHP silenciosas que ocorrem durante cron jobs — erros que normalmente nunca aparecem no log do admin.

Limpeza preventiva da tabela cron_schedule

A tabela cron_schedule cresce continuamente. O Magento limpa registros antigos automaticamente — mas apenas quando o cron está rodando. Em ambientes onde o cron para e retoma frequentemente, pode ser necessário limpar manualmente:

-- Manter apenas os últimos 7 dias
DELETE FROM cron_schedule
WHERE scheduled_at < NOW() - INTERVAL 7 DAY
  AND status IN ('success', 'missed', 'failed');