Un job Laravel qui tourne parfaitement en local avec queue:work et le driver sync ne dit presque rien de son comportement en production. En production, les workers crashent, les jobs sont relancés automatiquement après un échec, parfois plusieurs fois, et le même job peut s'exécuter deux fois pour des raisons totalement indépendantes du code métier. Sans stratégie explicite de retry, d'idempotence et de gestion des échecs définitifs, ce sont des effets de bord dupliqués - un email envoyé trois fois, une carte débitée deux fois - qui finissent par remonter en support client plutôt qu'en alerte technique.
Pourquoi un job "qui marche en dev" échoue en prod
En développement, un job s'exécute une fois, de façon synchrone ou via un unique worker lancé à la main, sans jamais être interrompu. En production, plusieurs mécanismes changent la donne : un déploiement qui redémarre les workers en plein traitement, un timeout PHP qui tue un job trop long, une exception réseau transitoire vers une API tierce, ou simplement plusieurs workers qui traitent la même file en parallèle. Laravel relance automatiquement un job qui échoue selon sa configuration de retry - ce qui est précisément le comportement souhaité pour une erreur transitoire, et précisément le problème si le job n'est pas conçu pour être rejoué sans risque.
Retries : le mécanisme réel
Chaque job peut définir son nombre de tentatives, sa stratégie de délai entre tentatives, et une limite de temps avant d'être considéré comme bloqué :
class ChargeCustomerInvoice implements ShouldQueue
{
use Queueable;
public int $tries = 5;
public int $maxExceptions = 3;
public function backoff(): array
{
// Délai croissant entre chaque tentative : 10s, 30s, 60s, 120s, 300s
return [10, 30, 60, 120, 300];
}
public function retryUntil(): \DateTime
{
// Après ce délai, le job est abandonné même s'il reste des tentatives
return now()->addHours(2);
}
public function handle(PaymentGateway $gateway): void
{
$gateway->charge($this->invoice);
}
public function failed(\Throwable $exception): void
{
// Appelé une seule fois, après l'échec définitif
Log::error('Invoice charge permanently failed', [
'invoice_id' => $this->invoice->id,
'exception' => $exception->getMessage(),
]);
}
}
Le piège classique est de laisser les valeurs par défaut ($tries = 1 sans backoff) pour un job qui appelle une API externe sujette à des erreurs transitoires - il échoue définitivement à la première coupure réseau, sans jamais être rejoué.
Idempotence : pourquoi un retry sans elle est dangereux
Un retry suppose implicitement que rejouer le job produit le même résultat que s'il n'avait jamais échoué. C'est vrai pour une opération de lecture, faux pour une opération qui a un effet de bord externe. Si ChargeCustomerInvoice a réussi côté passerelle de paiement mais que le job a échoué après ce point (timeout réseau sur la réponse, crash du worker), le retry suivant va débiter le client une seconde fois.
public function handle(PaymentGateway $gateway): void
{
// La clé d'idempotence doit être stable entre toutes les tentatives
// du même job, pas générée à chaque exécution
$idempotencyKey = "invoice-charge-{$this->invoice->id}";
$lock = Cache::lock("charge-lock-{$this->invoice->id}", 30);
if (! $lock->get()) {
// Un autre worker traite déjà cette facture, on relance plus tard
$this->release(15);
return;
}
try {
if ($this->invoice->refresh()->status === 'paid') {
// Déjà traité par une tentative précédente malgré l'échec apparent
return;
}
$gateway->charge($this->invoice, idempotencyKey: $idempotencyKey);
$this->invoice->update(['status' => 'paid']);
} finally {
$lock->release();
}
}
La plupart des passerelles de paiement (Stripe, par exemple) acceptent une clé d'idempotence côté API, ce qui garantit qu'un appel répété avec la même clé ne débite jamais deux fois, même si le réseau a perdu la réponse originale. Côté application, le verrou Cache::lock et la vérification de l'état déjà persisté sont le complément indispensable, parce que la passerelle externe ne protège pas contre deux workers Laravel qui traitent la même facture en parallèle.
Dead letters : où vont les jobs qui échouent définitivement
Quand un job épuise ses tentatives, Laravel l'écrit dans la table failed_jobs (ou son équivalent Horizon avec Redis) plutôt que de le perdre silencieusement. Cette table est la "dead letter queue" de Laravel - les jobs y échouent de façon définitive mais restent inspectables et rejouables :
# Lister les jobs en échec définitif
php artisan queue:failed
# Rejouer un job précis après correction du bug sous-jacent
php artisan queue:retry 15
# Rejouer tous les jobs échoués d'un lot donné
php artisan queue:retry --range=10,25
# Purger un job qu'on ne veut plus rejouer
php artisan queue:forget 15
Le point faible de ce mécanisme, souvent découvert trop tard, est qu'un job dans failed_jobs n'alerte personne par défaut. Sans intégration explicite - un listener sur l'événement JobFailed, une alerte Horizon, ou un webhook vers Slack/PagerDuty - des jobs critiques peuvent s'accumuler silencieusement pendant des jours.
Diagnostiquer en production
Trois signaux à surveiller en priorité, avant qu'un incident client ne les révèle :
- La taille de chaque file (
horizon:statusouphp artisan queue:monitor emails,payments --max=100), pour détecter un backlog qui grossit plus vite qu'il ne se vide. - Les workers qui redémarrent en boucle - souvent un signe de fuite mémoire causée par l'absence de
--max-jobsou--max-time, qui empêche le worker PHP de se recycler périodiquement. - Les jobs bloqués plus longtemps que leur
timeoutconfiguré, qui indiquent une dépendance externe lente plutôt qu'un bug de code.
; Configuration Supervisor type pour des workers résilients
[program:laravel-worker]
command=php /var/www/artisan queue:work redis --queue=payments --tries=5 --max-jobs=1000 --max-time=3600
autostart=true
autorestart=true
numprocs=4
stopwaitsecs=30
Le correctif, avec ses compromis
Le driver Redis combiné à Horizon donne une visibilité en temps réel (débit, latence, taux d'échec) qu'une table database ne fournit pas aussi bien, au prix d'une dépendance d'infrastructure supplémentaire. Le middleware WithoutOverlapping évite qu'un même job logique (même facture, même utilisateur) tourne en double sur deux workers, mais introduit une latence de traitement si le verrou reste pris plus longtemps que prévu. Enfin, distinguer explicitement les exceptions "retryables" (timeout réseau, erreur 5xx) des exceptions "définitives" (validation métier, carte refusée) via des classes d'exception dédiées évite de gaspiller des tentatives sur une erreur qui ne se résoudra jamais en rejouant le job.
public function handle(PaymentGateway $gateway): void
{
try {
$gateway->charge($this->invoice);
} catch (CardDeclinedException $e) {
// Erreur définitive : ne jamais relancer, échouer immédiatement
$this->fail($e);
} catch (GatewayTimeoutException $e) {
// Erreur transitoire : laisser le mécanisme de retry standard agir
throw $e;
}
}
Quand retries et dead letters ne suffisent pas
Pour un processus métier en plusieurs étapes (réserver un stock, puis débiter le client, puis déclencher l'expédition), relancer naïvement le job entier en cas d'échec à la troisième étape peut rejouer les deux premières, déjà réussies. La bonne réponse est un pattern de compensation explicite - chaque étape sait comment annuler son propre effet (release_stock, refund) plutôt que de compter sur le retry global pour "repartir de zéro" sans double effet.
Un autre cas limite est le job "poison" : un payload corrompu ou une classe de job renommée après un déploiement, qui échoue systématiquement dès la désérialisation, avant même d'atteindre handle(). Un tel job consomme ses tentatives instantanément et pollue les métriques d'échec sans jamais pouvoir être corrigé par un simple queue:retry. La prévention passe par un versionnement prudent des classes de job et par l'utilisation de Bus::batch() avec des callbacks then/catch pour isoler les échecs partiels d'un traitement par lot, plutôt que de laisser un seul job corrompu faire échouer la supervision de tout le lot.
À retenir
Un système de queues fiable en production repose sur trois piliers indissociables : des retries configurés par type d'erreur (pas une valeur par défaut unique), une idempotence garantie au niveau du job et de la ressource externe, et une surveillance active de la dead letter queue plutôt qu'une table failed_jobs qu'on consulte seulement après l'incident.
