Guide · RabbitMQ

Dépannage RabbitMQ : arbre de décision

Utilisez cette page pour le diagnostic et la résolution des incidents RabbitMQ : repérez le symptôme, lancez la vérification indiquée sous celui-ci, puis suivez la ligne qui correspond à ce que vous observez. Cette page s'adresse à quelqu'un qui a un problème en ce moment : elle indique quoi vérifier et ce que signifie le résultat. Pour la séquence complète de commandes une fois le problème identifié, utilisez le runbook d'incident. Commandes vérifiées le 29 octobre 2026 dans les manuels CLI de RabbitMQ 4.4 et sur rabbitmq.com.

Scott Sternloff

Par Scott Sternloff, Architecte d’entreprise senior

LinkedIn · Mis à jour le · Lecture : 14 min · 12 sections

Sur cette page

Lancez deux commandes avant d'échafauder une hypothèse

Lancez deux commandes avant d'échafauder une hypothèse

rabbitmq-diagnostics alarms vous indique si le broker a cessé d'accepter les publications, et rabbitmqctl list_queues -p <vhost> name messages consumers vous indique si quelque chose consomme. Une file d'attente qui grossit sans aucun consommateur est de loin le ticket « RabbitMQ est en panne » le plus fréquent que nous recevons, et la correction se trouve presque toujours dans l'application consommatrice. Repérez ensuite votre symptôme :

SymptômePremière vérification
File d'attente qui grossit sans se viderrabbitmqctl list_queues avec consumers et unacked
Alarme mémoire, éditeurs bloquésrabbitmq-diagnostics memory_breakdown
Alarme disquerabbitmq-diagnostics status, espace disque libre par rapport à la limite
Partition ou nœud injoignablerabbitmq-diagnostics cluster_status
Nœud qui ne démarre pas ou ne rejoint pas le clusterrabbitmq-diagnostics log_tail
Les clients ne peuvent pas se connecterrabbitmq-diagnostics listeners
Lien de fédération ou Shovel tombérabbitmqctl federation_status --only-down
Messages publiés mais jamais reçusrabbitmqctl list_bindings
Pods bloqués sur Kuberneteskubectl describe pod

À quoi sert cette page et ce qu'elle suppose

Il s'agit d'une table de correspondance entre symptômes et vérifications, pas d'un runbook : chaque section donne une première vérification et un tableau qui explique le résultat. Le runbook d'incident contient les séquences de commandes complètes et ordonnées pour les alarmes disque et mémoire, les partitions, la perte de quorum et la reprise d'un datacenter, et le guide des schémas de défaillance explique pourquoi chacun se produit. Servez-vous de cette page pour déterminer lequel il vous faut.

Elle suppose RabbitMQ 4.x. Depuis la 4.3.0, le metadata store est exclusivement Khepri et les anciennes stratégies de gestion des partitions ont disparu : les branches consacrées aux partitions sont donc rédigées pour Raft ; lorsqu'un cluster 4.2 ou antérieur se comporte différemment, la ligne le précise. Les symptômes sont ceux qui arrivent réellement au support AceMQ, tirés de nos tickets plutôt que d'une liste générique.

Une file d'attente grossit et ne se vide pas

Vérifiez avant tout le nombre de consommateurs sur cette file d'attente : c'est lui qui indique si le problème vient du broker ou de l'application.

rabbitmqctl list_queues -p <vhost> name type messages messages_unacknowledged consumers
Backlog de file d'attente : lisez les colonnes consumers et unacked
Si vous constatezCela signifie généralementQue faire
Consumers vaut 0Rien ne consomme. L'application consommatrice est arrêtée, a planté ou n'a pas réussi à se reconnecter après un redémarrage.Vérifiez l'application, pas le cluster. Le broker fait son travail.
Consumers supérieur à 0, unacked élevé et figéLes consommateurs détiennent des messages qu'ils n'acquittent jamais, généralement bloqués sur un appel aval sans timeout, ou sur un chemin de code qui n'acquitte jamais.Redémarrez les consommateurs pour libérer les messages, puis ajoutez le timeout ou l'acquittement manquant. Les quorum queues les restituent après le timeout consommateur (30 minutes par défaut).
Unacked proche de 0, messages toujours en hausseChaque consommateur suit le rythme, mais ils ne sont pas assez nombreux, ou le prefetch est trop bas pour les occuper.Ajoutez des consommateurs et augmentez le prefetch avant de toucher au broker. La documentation situe l'optimum de débit habituel entre 100 et 300.
Les consommateurs se déconnectent et se reconnectent sans cesseUn timeout d'inactivité de load balancer ou de pare-feu plus court que le heartbeat, ou un canal fermé avec PRECONDITION_FAILED par le timeout d'acquittement de livraison.Réglez le heartbeat en dessous de chaque timeout d'inactivité sur le chemin, et cherchez l'erreur de timeout dans le journal client avant d'augmenter <code>consumer_timeout</code>.
Tableau · Backlog de file d'attente : lisez les colonnes consumers et unacked. Faites défiler horizontalement sur petit écran.

Une alarme mémoire s'est déclenchée et la publication est bloquée

Confirmez l'alarme et identifiez ce qui occupe la mémoire : la ventilation indique s'il s'agit d'un backlog, d'un problème de connexions ou d'un problème de dimensionnement.

rabbitmq-diagnostics alarms
rabbitmq-diagnostics memory_breakdown --unit "MB"
Alarme mémoire : lisez les plus grosses catégories de la ventilation
Si vous constatezCela signifie généralementQue faire
<code>queue_procs</code> ou la mémoire des quorum queues domineUn backlog est la cause et l'alarme le symptôme.Suivez la section 1. L'alarme disparaît quand les files d'attente se vident.
<code>connection_*</code> ou <code>binary</code> domineDe nombreuses connexions, des messages volumineux ou un client qui ouvre une connexion par opération.Comparez <code>rabbitmqctl list_connections name user</code> à ce que vous attendez et repérez le client qui multiplie les connexions.
Rien ne domine et la limite semble basseLe watermark a été abaissé sous la valeur par défaut de 0.6, ou le nœud est sous-dimensionné pour la charge.Vérifiez la limite dans <code>rabbitmq-diagnostics status</code>. La documentation recommande 0.4 à 0.7 et au moins 30 % laissés à l'OS ; dépasser 0.7 exige un monitoring de la mémoire en place : redimensionnez donc avant de l'augmenter.
La mémoire monte régulièrement sans croissance des files d'attenteUne file d'attente non bornée que personne ne surveille, ou la mémoire du write-ahead log des quorum queues.Bornez les files d'attente. Sur les nœuds hébergeant des quorum queues, la documentation préconise d'allouer au moins trois fois la taille limite du WAL, soit 512 MiB par défaut.
Tableau · Alarme mémoire : lisez les plus grosses catégories de la ventilation. Faites défiler horizontalement sur petit écran.

Une alarme disque s'est déclenchée

Comparez l'espace libre à la limite configurée, sur le volume qui contient réellement le répertoire de données.

rabbitmq-diagnostics alarms
rabbitmq-diagnostics status | grep -A 2 -B 2 "Node data directory"
Alarme disque
Si vous constatezCela signifie généralementQue faire
Le disque est réellement pleinUn backlog sur des quorum queues ou des streams, qui conservent tout sur disque et ne récupèrent pas forcément tout de suite l'espace des messages consommés.Videz ou supprimez la plus grosse file d'attente, puis agrandissez le volume. En cas de doute, la documentation conseille de surdimensionner le disque.
L'espace libre semble suffisant mais l'alarme persisteLa limite est plus élevée que vous ne le pensez, ou le répertoire de données se trouve sur un autre volume que celui que vous avez vérifié.Confirmez le chemin du répertoire de données avec la commande ci-dessus avant toute modification.
Tableau · Alarme disque. Faites défiler horizontalement sur petit écran.

Un nœud est injoignable ou le cluster s'est partitionné

Déterminez quel côté détient la majorité avant de toucher à quoi que ce soit : avec Raft, le côté majoritaire continue de fonctionner et le côté minoritaire attend.

rabbitmq-diagnostics cluster_status
rabbitmq-queues quorum_status <queue>
rabbitmq-diagnostics check_if_node_is_quorum_critical
Partitions sous RabbitMQ 4.3 et versions ultérieures (Khepri et quorum queues)
Si vous constatezCela signifie généralementQue faire
Un nœud absent des nœuds actifs, les autres joignablesFonctionnement normal. La majorité a élu de nouveaux leaders en quelques secondes ; les livraisons des quorum queues ne sont suspendues que du côté isolé.Rétablissez le réseau. Le membre qui revient se resynchronise auprès du leader et ne peut pas devenir leader avant d'avoir rattrapé son retard. Ne le réinitialisez pas.
Aucun côté ne détient la majoritéLes publications, les acquittements et les modifications de métadonnées ne peuvent pas progresser ; ils attendent une majorité ou expirent.Ramenez les nœuds plutôt que d'en réinitialiser un. Si la seule issue implique de supprimer les données d'un nœud, arrêtez-vous et escaladez.
Le nœud isolé était une VM suspendue ou migréeUne partition de type suspension/reprise : le nœud ne pense pas avoir été défaillant, ses pairs si.Traitée comme toute partition à nœud unique ; les suspensions courtes sont gérées. Vérifiez le calendrier de migrations et de snapshots de l'hyperviseur.
Des partitions se répètent sur un cluster étendu sur plusieurs régions ou zonesC'est la topologie, pas une panne. Le trafic entre nœuds tolère mal une latence ou une gigue élevées.Exploitez des clusters distincts reliés par fédération ou Shovel pour le trafic intersites.
4.2 ou antérieure, avec <code>autoheal</code> ou <code>ignore</code>Les deux côtés ont pu accepter des écritures : il y a donc une divergence à réconcilier.Conservez le côté majoritaire aux données les plus complètes, redémarrez les nœuds de l'autre côté pour qu'ils rejoignent le cluster, puis passez à <code>pause_minority</code>.
Tableau · Partitions sous RabbitMQ 4.3 et versions ultérieures (Khepri et quorum queues). Faites défiler horizontalement sur petit écran.

Un nœud ne démarre pas ou ne rejoint pas le cluster

Lisez le journal avant de redémarrer quoi que ce soit une seconde fois : la cause se trouve presque toujours dans la première erreur.

rabbitmq-diagnostics log_tail -N 200
rabbitmq-diagnostics check_running
rabbitmq-diagnostics cluster_status
Échecs de démarrage et de réintégration de nœuds
Si vous constatezCela signifie généralementQue faire
Erreurs de cookie ou d'authentificationLe cookie Erlang partagé diffère entre les nœuds, ou entre la CLI et le nœud.Comparez <code>rabbitmq-diagnostics erlang_cookie_hash</code> sur chaque nœud, puis corrigez le fichier, son propriétaire et ses permissions.
Erreurs <code>epmd</code> ou <code>nxdomain</code>Résolution de noms. Sur Kubernetes, la documentation de l'opérateur met en cause le cache CoreDNS ; nous le voyons aussi sur des clusters IPv6 uniquement où Erlang n'a pas été configuré pour IPv6.Corrigez le DNS ou la résolution du nom d'hôte du nœud, pas RabbitMQ. Voir la section 9 pour le cas Kubernetes.
Le nœud n'est pas sur la même version de RabbitMQ que les autresIl est désynchronisé en pleine mise à niveau.Alignez son logiciel sur la version majoritaire et laissez-le rejoindre le cluster. Ne rétrogradez pas le cluster pour vous aligner sur lui : le guide de mise à niveau indique que les rétrogradations ne sont pas prises en charge.
Erreurs de descripteurs de fichiers ou <code>emfile</code>La limite de fichiers ouverts est trop basse. Les connexions, les files d'attente et les fichiers de segments des quorum queues sont tous comptabilisés.Augmentez la limite du service. La documentation demande au moins 50 000, ou deux fois le nombre de connexions au 95e centile plus le nombre de files d'attente.
Tableau · Échecs de démarrage et de réintégration de nœuds. Faites défiler horizontalement sur petit écran.

Objectifs de réponse à partir de 15 minutes, selon le plan. Ingénieurs seniors attitrés.

Nous contacter

Les clients ne peuvent pas se connecter ou échouent à l'authentification

Déterminez s'il s'agit du listener, de TLS ou des identifiants, dans cet ordre.

rabbitmq-diagnostics listeners
rabbitmq-diagnostics check_port_connectivity
rabbitmq-diagnostics check_certificate_expiration
Échecs de connexion
Si vous constatezCela signifie généralementQue faire
Échecs sur le port 5671 mentionnant des certificatsLe nom du certificat ne correspond pas au nom d'hôte utilisé par les clients, il a expiré, ou un load balancer termine TLS alors que les clients attendent le certificat du broker.Testez avec <code>openssl s_client -connect &lt;host&gt;:5671 -servername &lt;host&gt;</code> en utilisant le nom employé par le client.
TLS de fédération, Shovel ou LDAP en échec après une mise à niveau d'ErlangDepuis Erlang 26, la vérification du pair côté client TLS est activée par défaut : ces liens échouent donc sans certificat et clé client.Configurez la paire certificat/clé, ou désactivez sciemment la vérification du pair.
L'authentification échoue pour une seule applicationSon utilisateur n'a aucune permission sur le vhost qu'il ouvre, même si le mot de passe est correct.Vérifiez <code>rabbitmqctl list_user_permissions &lt;user&gt;</code>, pas seulement le mot de passe.
Connexion refusée juste après un redémarrageLe nœud est encore en cours de démarrage, ou une alarme bloque.Lancez <code>rabbitmq-diagnostics alarms</code> avant d'incriminer le réseau.
Tableau · Échecs de connexion. Faites défiler horizontalement sur petit écran.

Des liens de fédération ou Shovel sont tombés

Listez les liens et leur état, et comparez-les à une liste écrite de ce qui devrait exister.

rabbitmqctl federation_status --only-down
rabbitmqctl shovel_status
rabbitmqctl list_parameters -p <vhost>
Liens de fédération et Shovel
Si vous constatezCela signifie généralementQue faire
Tous les liens ont redémarré en même tempsD'après notre expérience, c'est attendu après un changement de composition du cluster, comme l'ajout ou le remplacement d'un nœud.La seule question est de savoir s'ils sont tous revenus, ce qui suppose une liste de ce qui devrait exister.
Un lien refuse de s'établirLes identifiants, le chemin réseau vers l'amont, ou un vhost amont qui n'existe plus. Ces échecs se situent généralement côté amont et ressemblent à des problèmes côté aval.Vérifiez l'URI et l'utilisateur amont, testez le chemin et confirmez le vhost. Pour les liens TLS, voir la ligne Erlang 26 de la section 6.
Tableau · Liens de fédération et Shovel. Faites défiler horizontalement sur petit écran.

Des messages sont publiés mais jamais reçus

Vérifiez d'abord que le message est bien routé : un exchange sans binding correspondant supprime par défaut les messages sans erreur.

rabbitmqctl list_exchanges -p <vhost> name type
rabbitmqctl list_bindings -p <vhost>
Messages perdus ou mal routés
Si vous constatezCela signifie généralementQue faire
Aucun binding ne correspond à la clé de routageLe message n'est pas routable. Avec <code>mandatory</code> à false, la valeur par défaut, il est supprimé sauf si un alternate exchange est défini.Ajoutez un alternate exchange pour que les messages non routables aboutissent à un endroit visible, et surveillez <code>rabbitmq_global_messages_unroutable_dropped_total</code>.
Les bindings semblent corrects mais le mauvais consommateur reçoit les messagesChevauchement de jokers de topic : deux bindings correspondent et les deux files d'attente reçoivent une copie.Resserrez les motifs de binding.
Des messages apparaissent dans la dead-letter queue (DLQ)Quelque chose les a rejetés ou fait expirer : TTL, limite de longueur, rejet sans remise en file, ou limite de livraison des quorum queues (20 par défaut depuis la 4.0).Lisez l'en-tête <code>x-death</code> d'un message dead-lettered ; il indique la raison et la file d'attente.
Tableau · Messages perdus ou mal routés. Faites défiler horizontalement sur petit écran.

Des pods ne démarrent pas ou ne s'arrêtent pas sur Kubernetes

Lisez d'abord les événements du pod : la plupart des causes sont extérieures à RabbitMQ.

kubectl describe pod <pod> -n <namespace>
kubectl logs <pod> -n <namespace>
kubectl describe rmq <cluster> -n <namespace>
Problèmes de pods Kubernetes
Si vous constatezCela signifie généralementQue faire
<code>ImagePullBackOff</code>Identifiants du registre.Le secret doit exister dans le namespace du pod et figurer sous <code>imagePullSecrets</code> dans la spec RabbitmqCluster.
Pods bloqués en cours d'arrêtLe hook preStop de l'opérateur retient un pod critique pour le quorum, généralement à cause d'une quorum queue résiduelle.Vérifiez d'abord l'état du quorum. Ne forcez la suppression qu'une fois certain que la perte des données de ce membre est acceptable.
Les pods redémarrent avec une erreur <code>epmd</code> <code>nxdomain</code>Les nœuds résolvent les noms d'hôte de leurs pairs au démarrage et le cache DNS est obsolète.La documentation de l'opérateur suggère de réduire le cache CoreDNS de 30 secondes à 5 à 10.
Le conteneur échoue sous une politique non-root imposéeLes paramètres du security context ne correspondent pas à l'image.Définissez <code>runAsUser</code>, <code>runAsGroup</code> et <code>fsGroup</code> de façon cohérente ; <code>fsGroup</code> détermine si le broker peut écrire sur son volume.
Tableau · Problèmes de pods Kubernetes. Faites défiler horizontalement sur petit écran.

Dépannage RabbitMQ avec l'interface de gestion, les journaux et les métriques

Les sections ci-dessus partent d'un symptôme. Si aucune n'explique le problème, voici où recueillir des éléments avant de modifier quoi que ce soit. Chaque source répond à une question différente, et aucune ne remplace les deux premières commandes en haut de page.

Sources d'information et usage de chacune
SourceÀ utiliser pourComment y accéder
Interface de gestion RabbitMQVisualiser les débits de messages globalement et par file d'attente, exchange ou canal, et confirmer si un backlog grossit ou reste stable.Activez le plugin avec <code>rabbitmq-plugins enable rabbitmq_management</code> (sans redémarrage), puis ouvrez <code>http://&lt;node-hostname&gt;:15672/</code>. Lancez <code>rabbitmq-plugins list</code> pour vérifier qu'il est actif. N'en faites pas votre source d'alertes : le guide de monitoring précise que le plugin de gestion consomme davantage de mémoire et ne conserve que quelques heures d'historique.
JournauxLa première erreur derrière un nœud qui ne démarre pas, une connexion refusée ou une alarme.<code>rabbitmq-diagnostics -q log_location</code> affiche le chemin. Le niveau par défaut est <code>info</code>. <code>rabbitmqctl set_log_level debug</code> l'augmente sur un nœud en cours d'exécution mais ne survit pas à un redémarrage : pensez à le rétablir ensuite.
Événements de connexion clientDistinguer un problème réseau d'un problème d'authentification.Les nœuds journalisent les principaux événements du cycle de vie des connexions, mais seulement une fois la connexion TCP établie et au moins un octet envoyé par le pair. Si rien n'est journalisé pour un client, sa connexion n'a jamais atteint le nœud : examinez le chemin réseau et le listener sur le port 5672 ou 5671.
Capture de paquetsLes cas où les journaux ne montrent rien et où vous devez voir ce qui transite sur le réseau.Le guide de diagnostic réseau cite <code>tcpdump</code> et Wireshark, qui comprennent tous deux chaque protocole pris en charge par RabbitMQ. Capturez côté nœud et côté client, puis comparez.
Métriques PrometheusLes tendances sur plusieurs jours et une alerte avant le prochain incident.Collectez les métriques du plugin <code>rabbitmq_prometheus</code> sur le port 15692. Le pack de règles d'alerte contient les règles.
Tableau · Sources d'information et usage de chacune. Faites défiler horizontalement sur petit écran.

Quand s'arrêter et escalader

Escaladez lorsque l'étape suivante est destructive et non testée. Trois situations justifient un regard extérieur plutôt qu'une heure de plus de votre côté : aucun côté du cluster n'a la majorité et l'issue implique de supprimer les données d'un nœud ; un nœud ne rejoint pas le cluster après une mise à niveau ; une partition en 4.2 ou antérieure où les deux côtés ont accepté des écritures et où vous devez choisir quelles données conserver. Dans les trois cas, l'improvisation aggrave la situation.

Avec un contrat de support AceMQ, un ingénieur senior prend en charge un P1 avec des objectifs de réponse à partir de 15 minutes, selon le plan, 24/7. Sans contrat, le service de diagnostic et de résolution lance une mission d'urgence, et si la cause s'avère être l'application consommatrice plutôt que le broker, nous vous le dirons aussi.

Questions fréquentes

Pourquoi ma file d'attente RabbitMQ ne se vide-t-elle pas ?

Vérifiez d'abord le nombre de consommateurs sur cette file d'attente. Zéro consommateur signifie que rien ne consomme et que le problème se situe dans l'application consommatrice. Des consommateurs présents avec un nombre de messages non acquittés élevé et figé signifie qu'ils détiennent des messages qu'ils n'acquittent jamais, généralement bloqués sur un appel aval sans timeout. Un nombre de messages non acquittés proche de zéro avec une file qui grossit signifie qu'il n'y a pas assez de consommateurs ou que le prefetch est trop bas.

Qu'est-ce qui déclenche une alarme mémoire RabbitMQ ?

Lancez rabbitmq-diagnostics memory_breakdown. Si la mémoire des files d'attente domine, un backlog est en cause et l'alarme disparaît quand il se résorbe. Si la mémoire des connexions ou binary domine, cherchez un excès de connexions ou des messages volumineux. Si rien ne domine, vérifiez le watermark : la valeur par défaut est 0.6 de la mémoire disponible, et la documentation recommande de rester entre 0.4 et 0.7.

Que faire face à une partition réseau RabbitMQ en 4.x ?

À partir de la 4.3, il n'y a plus de stratégie de gestion des partitions à choisir : Khepri, les quorum queues et les streams utilisent tous Raft, donc le côté majoritaire continue de fonctionner et le côté minoritaire attend. Identifiez la majorité avec rabbitmq-diagnostics cluster_status, rétablissez le réseau et laissez les nœuds qui reviennent se resynchroniser. Ne réinitialisez pas de nœuds pour accélérer le processus.

Pourquoi des messages publiés dans RabbitMQ ne sont-ils jamais livrés ?

Généralement parce qu'aucun binding ne correspond à la clé de routage : le message n'est pas routable et il est supprimé silencieusement, sauf si l'éditeur définit mandatory ou si l'exchange dispose d'un alternate exchange. Vérifiez les bindings avec rabbitmqctl list_bindings et ajoutez un alternate exchange pour rendre visibles les messages non routables.

Où se trouvent les journaux RabbitMQ et comment obtenir plus de détails ?

Lancez rabbitmq-diagnostics -q log_location sur le nœud pour afficher le chemin ; l'interface de gestion l'indique aussi sur la page du nœud. Le niveau de journalisation par défaut est info. Pour obtenir une sortie debug sur un nœud en cours d'exécution, utilisez rabbitmqctl set_log_level debug, en gardant à l'esprit que ce changement est temporaire et perdu au redémarrage.

Comment diagnostiquer les problèmes de connexion client RabbitMQ ?

Lancez rabbitmq-diagnostics listeners pour confirmer que le port est ouvert, puis lisez le journal du nœud : il enregistre les événements du cycle de vie des connexions client, mais uniquement pour celles qui ont achevé une négociation TCP et envoyé des données. Aucune entrée signifie que la connexion n'a jamais atteint le nœud : vérifiez le réseau. Un échec d'authentification journalisé désigne plutôt l'utilisateur, le mot de passe ou les permissions sur le vhost. Si les journaux restent muets, capturez le trafic avec tcpdump ou Wireshark.

Consultation gratuite

Un regard expert sur votre cluster RabbitMQ

Que vous deviez résoudre un incident de production, planifier une migration ou obtenir un second avis sur votre architecture, notre équipe est prête. Pas d’argumentaire commercial, seulement des réponses.

Nous écrire