Erreurs courantes de Kafka et solutions avec exemples pratiques

Introduction

Apache Kafka est une plateforme de diffusion en continu distribuée sur laquelle des milliers d'entreprises s'appuient pour des pipelines de données en temps réel et des architectures pilotées par événements. Lorsque Kafka tombe en panne, l'impact se propage rapidement : les consommateurs se bloquent, les producteurs expirent et les tableaux de bord deviennent obsolètes. Ce guide rassemble les erreurs Kafka les plus courantes, leurs causes et des solutions étape par étape. Chaque problème comprend des commandes concrètes, les sorties attendues et des étapes de vérification pour passer du symptôme observé à une résolution confirmée.

Cet article s'adresse aux développeurs, aux consultants DevOps et aux équipes techniques de startups qui exploitent des clusters Kafka ou construisent des applications par-dessus. Il relie les messages d'erreur Kafka, les techniques de débogage et les modèles de dépannage aux commandes spécifiques à chaque version et aux décisions de récupération. Les exemples supposent un déploiement Kafka version 2.8 ou ultérieure, mais signalent les différences là où elles comptent.

La sécurité opérationnelle est le principe fondamental : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés au lieu de secrets, vérifier le résultat et documenter comment récupérer si l'état attendu n'est pas atteint. L'article évite de stocker de véritables identifiants, jetons, clés privées ou identifiants de production dans les commandes ou les sorties.

Inventaire de la version et de l'environnement

Avant de modifier quoi que ce soit, identifiez la version Kafka installée, la topologie de déploiement et le composant défaillant. Les erreurs Kafka semblent souvent identiques entre les brokers, les producteurs, les consommateurs, ZooKeeper ou les nœuds de métadonnées KRaft, mais la correction appropriée dépend du composant et de la version. Utilisez les commandes adaptées à la version issues de la documentation officielle et capturez l'état en lecture seule avant toute intervention.

Collecter la base de référence

Sur chaque hôte de broker ou de client, exécutez :

kafka-topics.sh --version

Sortie attendue (exemple) :

3.6.1 (Commit:... )

Si la commande n'est pas trouvée, les binaires Kafka ne sont pas dans le PATH. Localisez le répertoire d'installation de Kafka, généralement /opt/kafka ou /usr/local/kafka, et utilisez le chemin complet :

/opt/kafka/bin/kafka-topics.sh --version

Vérifiez le fichier server.properties du broker pour les écouteurs annoncés et les répertoires de journaux :

grep -E '^(broker.id|advertised.listeners|log.dirs|zookeeper.connect|process.roles)' /opt/kafka/config/server.properties

Exemple de sortie :

broker.id=1
advertised.listeners=PLAINTEXT://broker1:9092
log.dirs=/var/lib/kafka/data
zookeeper.connect=zookeeper1:2181,zookeeper2:2181,zookeeper3:2181

Pour les clusters KRaft (Kafka 3.3+), inspectez plutôt les propriétés de métadonnées :

grep -E '^(process.roles|node.id|controller.quorum.voters|advertised.listeners)' /opt/kafka/config/server.properties

Exemple de sortie :

process.roles=broker,controller
node.id=1
controller.quorum.voters=1@kafka1:9093
advertised.listeners=PLAINTEXT://kafka1:9092

Enregistrez la version Kafka, la topologie (IDs de broker, ensemble ZooKeeper ou quorum KRaft) et le composant sous investigation. Sauvegardez cette base de référence avant de faire des changements.

Observer la santé du broker en lecture seule

Vérifiez si les brokers sont opérationnels et connectés à ZooKeeper (en mode ZooKeeper) ou au quorum de métadonnées KRaft. Utilisez kafka-broker-api-versions.sh pour interroger un broker sans produire ni consommer :

kafka-broker-api-versions.sh --bootstrap-server broker1:9092

Un broker sain renvoie une liste des versions d'API prises en charge. Si la commande expire, le broker n'écoute pas. Vérifiez l'accessibilité réseau et les journaux du broker sous /var/log/kafka/server.log pour les entrées FATAL ou ERROR.

Un moyen en lecture seule de lister les topics et leurs métadonnées :

kafka-topics.sh --bootstrap-server broker1:9092 --list

Sortie attendue (exemple) :

__consumer_offsets
orders
payments

Si la commande se bloque ou renvoie Timed out waiting for a node assignment, le broker peut faire partie d'un cluster en échec. Ne redémarrez pas les services aveuglément ; collectez d'abord les journaux et les horodatages.

Protéger les secrets et les espaces réservés

Ne collez jamais de vrais mots de passe ou certificats dans un historique de terminal ou un article. Utilisez des variables d'environnement :

export KAFKA_SASL_PASSWORD='<remplacez-par-le-mot-de-passe>'

Dans les extraits de configuration, utilisez <votre-bootstrap-server>, <votre-topic>, <votre-groupe-de-consommateurs>. Lorsque vous devez référencer un fichier, utilisez un chemin comme /etc/kafka/secrets/client.truststore.jks plutôt que d'imprimer le contenu.

Chemin de configuration sûr

Les erreurs de configuration causent de nombreuses pannes Kafka. Un chemin sûr signifie : afficher la configuration effective en lecture seule, modifier un paramètre à la fois et vérifier avec une commande qui renvoie le nouvel état.

Inspecter la configuration du broker

La configuration du broker se trouve dans server.properties ou dans des variables d'environnement. Pour voir les paramètres actuels du broker sans redémarrer, utilisez les outils de configuration dynamique de Kafka (Kafka 2.2+) :

kafka-configs.sh --bootstrap-server broker1:9092 --entity-type brokers --entity-name 1 --describe

Exemple de sortie :

Dynamic configs for broker 1 are:
  min.insync.replicas=2 sensitive=false synonyms={DYNAMIC_BROKER_CONFIG:min.insync.replicas=2}
  unclean.leader.election.enable=false sensitive=false synonyms={DYNAMIC_BROKER_CONFIG:unclean.leader.election.enable=false}

La sortie montre l'origine de chaque config (DYNAMIC_BROKER_CONFIG, STATIC_BROKER_CONFIG, DEFAULT_CONFIG). Utilisez-la pour déterminer si un changement nécessite un redémarrage roulant ou peut être appliqué dynamiquement.

Modifier un paramètre avec vérification

Exemple : augmenter replication.factor pour un topic. Vérifiez d'abord la configuration actuelle du topic :

kafka-configs.sh --bootstrap-server broker1:9092 --entity-type topics --entity-name orders --describe

Exemple de sortie :

Dynamic configs for topic orders are:
  retention.ms=604800000 sensitive=false synonyms={STATIC_TOPIC_CONFIG:retention.ms=604800000}
  min.insync.replicas=1 sensitive=false synonyms={DEFAULT_CONFIG:min.insync.replicas=1}

Pour modifier retention.ms à 3 jours dynamiquement :

kafka-configs.sh --bootstrap-server broker1:9092 --entity-type topics --entity-name orders --alter --add-config retention.ms=259200000

Sortie attendue :

Completed updating config for topic orders.

Vérifiez :

kafka-configs.sh --bootstrap-server broker1:9092 --entity-type topics --entity-name orders --describe | grep retention.ms

Si la modification n'apparaît pas, vérifiez que le broker accepte les configurations dynamiques et que vous disposez des ACL requis.

Revenir en arrière en toute sécurité

Sachez toujours comment revenir en arrière. Pour une configuration de topic, vous pouvez supprimer la dérogation dynamique :

kafka-configs.sh --bootstrap-server broker1:9092 --entity-type topics --entity-name orders --alter --delete-config retention.ms

Cela restaure la valeur statique ou par défaut précédente. Relancez la commande --describe pour confirmer.

Vérification et diagnostics

Après tout changement, vérifiez que le cluster, les producteurs et les consommateurs se comportent comme prévu. Utilisez des commandes en lecture seule et examinez les métriques et les journaux.

Vérifier les métadonnées des topics et des partitions

Confirmez que le topic existe, qu'il a le bon nombre de partitions et de réplicas, et que les leaders sont disponibles :

kafka-topics.sh --bootstrap-server broker1:9092 --describe --topic orders

Exemple de sortie :

Topic: orders	PartitionCount: 3	ReplicationFactor: 3	Configs: segment.bytes=1073741824
	Topic: orders	Partition: 0	Leader: 1	Replicas: 1,2,3	Isr: 1,2,3
	Topic: orders	Partition: 1	Leader: 2	Replicas: 2,3,1	Isr: 2,3,1
	Topic: orders	Partition: 2	Leader: 3	Replicas: 3,1,2	Isr: 3,1,2

Vérifiez que chaque partition a un nombre de réplicas synchronisés (ISR) égal au facteur de réplication. Si l'ISR est inférieur aux réplicas, un broker peut être en panne ou en retard.

Vérifier le retard des groupes de consommateurs

Le retard des groupes de consommateurs est un indicateur de santé clé. Utilisez kafka-consumer-groups.sh :

kafka-consumer-groups.sh --bootstrap-server broker1:9092 --describe --group payments-group

Exemple de sortie :

GROUP           TOPIC           PARTITION  CURRENT-OFFSET  LOG-END-OFFSET  LAG  CONSUMER-ID     HOST            CLIENT-ID
payments-group  payments        0          100             150             50   consumer-1-...  /10.0.0.5       consumer-1
payments-group  payments        1          200             250             50   consumer-1-...  /10.0.0.5       consumer-1

Si LAG est constamment élevé, les consommateurs sont trop lents ou sont bloqués. Vérifiez les goulots d'étranglement de traitement ou les boucles de rééquilibrage.

Vérifier les journaux du broker pour les erreurs

Suivez le journal du broker et filtrez les modèles d'erreur courants :

tail -f /var/log/kafka/server.log | grep -E 'ERROR|FATAL|WARN'

Messages d'erreur courants et leur signification :

• ERROR [ReplicaFetcherThread-0-1]: Error in fetch ... indique des problèmes de réplication de broker à broker ; vérifiez le réseau et le disque.
• WARN [RequestSendThread controllerId=...] Controller ... epoch ... peut indiquer un basculement de contrôleur ; examinez les journaux du contrôleur.
• ERROR [Log partition=orders-0, dir=/var/lib/kafka/data] ... pointe vers un disque plein ou une corruption de segment ; exécutez df -h et kafka-log-dirs.sh --describe.

Utilisez kafka-log-dirs.sh pour inspecter la santé des répertoires de journaux :

kafka-log-dirs.sh --bootstrap-server broker1:9092 --describe --broker-list 1

Exemple de sortie :

{"broker":1,"logDirs":[{"logDir":"/var/lib/kafka/data","error":null,"partitions":[{"partition":"orders-0","size":123456,"offsetLag":0,"isFuture":false}]}]}

Le champ error doit être null. Sinon, examinez le disque.

Modes de défaillance et récupération

Les pannes Kafka se répartissent généralement en quelques catégories : broker en panne, ZooKeeper/KRaft indisponible, disque plein, délais d'attente du producteur, problèmes de rééquilibrage des consommateurs et erreurs de configuration. Cette section couvre chacune avec des étapes de récupération.

Broker en panne

Symptôme : les producteurs échouent avec Connection to node -1 failed, les consommateurs enregistrent Connection refused.

Diagnostic : vérifiez le processus du broker et le port.

ps aux | grep kafka.Kafka
ss -tuln | grep 9092

Si le processus est absent, vérifiez systemctl status kafka (s'il est exécuté en tant que service systemd) ou le statut du pod Docker/Kubernetes. Affichez les dernières lignes de server.log :

tail -n 100 /var/log/kafka/server.log

Causes courantes :

• Mémoire JVM insuffisante : le journal contient java.lang.OutOfMemoryError. Augmentez le tas dans KAFKA_HEAP_OPTS et redémarrez.
• Corruption du répertoire de données : le journal contient CorruptIndexException ou FileNotFoundException. Restaurez à partir d'une sauvegarde ou supprimez le répertoire de partition corrompu uniquement après avoir arrêté le broker et assuré la réplication ailleurs.
• Conflit de port : un autre processus sur 9092. Modifiez listeners ou arrêtez le processus en conflit.

Récupération : après avoir corrigé la cause racine, redémarrez le broker. Attendez qu'il rejoigne le cluster et rattrape les réplicas. Vérifiez :

kafka-broker-api-versions.sh --bootstrap-server broker1:9092

et vérifiez l'ISR pour les topics. Si un broker a été en panne pendant longtemps et est sorti de l'ISR, ses réplicas doivent rattraper. Surveillez kafka-topics.sh --describe jusqu'à ce que l'ISR revienne à la normale.

Défaillance de l'ensemble ZooKeeper

Symptôme : les brokers ne peuvent pas s'enregistrer ni élire un contrôleur ; erreurs comme ZooKeeper session expired ou Unable to connect to zookeeper server within timeout.

Diagnostic : vérifiez le statut de ZooKeeper sur chaque nœud :

echo stat | nc zookeeper1 2181 | grep Mode

Sortie attendue :

Mode: follower

ou Mode: leader.

Si aucune sortie, ZooKeeper n'est pas en cours d'exécution. Démarrez-le avec zkServer.sh start. Si l'ensemble est entièrement en panne, vous devez redémarrer au moins une majorité de nœuds (2 sur 3 ou 3 sur 5) pour former un quorum. Vérifiez les journaux ZooKeeper sous /var/log/zookeeper/zookeeper.out pour les exceptions.

Après la récupération de ZooKeeper, les brokers Kafka se reconnectent automatiquement. Vérifiez l'enregistrement du broker :

kafka-broker-api-versions.sh --bootstrap-server broker1:9092

Si les brokers ne se reconnectent pas, redémarrez-les un par un.

Défaillance du quorum de métadonnées KRaft

Pour les clusters KRaft, si le quorum du contrôleur perd sa majorité, aucun leader ne peut être élu. Vérifiez kafka-metadata-quorum.sh :

kafka-metadata-quorum.sh --bootstrap-server broker1:9092 describe --status

Sortie attendue :

ClusterId:          abc123...
LeaderId:           1
LeaderEpoch:        15
HighWatermark:      4000
MaxFollowerLag:     0
MaxFollowerLagTimeMs: 0
CurrentVoters:      [1,2,3]
CurrentObservers:   []

Si LeaderId est -1, il n'y a pas de leader actif. Rétablissez le quorum en vous assurant qu'au moins une majorité de nœuds contrôleurs sont en cours d'exécution et peuvent communiquer. Vérifiez les ACL réseau et les règles de pare-feu entre les contrôleurs.

Disque plein

Symptôme : les brokers renvoient java.io.IOException: No space left on device ou Error while writing to log. Les producteurs reçoivent RecordTooLargeException si le disque bloque les écritures.

Diagnostic :

df -h /var/lib/kafka/data

Si l'utilisation dépasse 85 %, agissez. Identifiez les topics ou partitions volumineux :

kafka-log-dirs.sh --bootstrap-server broker1:9092 --describe --broker-list 1

Options de récupération :

• Réduire la rétention du topic (mais faites-le avec précaution) :

  kafka-configs.sh --bootstrap-server broker1:9092 --entity-type topics --entity-name orders --alter --add-config retention.ms=86400000

Cela définit la rétention à 24 heures. Vérifiez avec --describe.

• Ajouter plus d'espace disque ou déplacer les répertoires de journaux. Pour déplacer un répertoire de journaux, copiez les données vers le nouvel emplacement pendant que le broker est arrêté, mettez à jour log.dirs, puis redémarrez.

• Supprimer les topics inutilisés après confirmation avec les parties prenantes. Utilisez kafka-topics.sh --delete. Assurez-vous que delete.topic.enable=true sur les brokers.

Délais d'attente et erreurs du producteur

Erreurs courantes du producteur :

• org.apache.kafka.common.errors.TimeoutException: Expiring 1 record(s) for topic orders-0: 30000 ms has passed since batch creation
• Cause : broker inaccessible ou tampon du producteur plein.
• Correction : vérifiez le réseau, la santé du broker et augmentez delivery.timeout.ms si nécessaire, mais vérifiez d'abord max.block.ms et batch.size.
• org.apache.kafka.common.errors.RecordTooLargeException
• Cause : l'enregistrement dépasse max.request.size du producteur ou message.max.bytes du broker.
• Correction : augmentez message.max.bytes du broker, max.message.bytes du topic et max.request.size du producteur à une valeur cohérente. Par exemple, définissez tous à 10485760 (10 Mo). Vérifiez avec kafka-configs.sh.
• org.apache.kafka.common.errors.NotLeaderForPartitionException
• Cause : le producteur envoie à un broker qui n'est pas le leader de la partition ; généralement transitoire pendant l'élection du leader.
• Correction : attendez la fin de l'élection du leader ; vérifiez kafka-topics.sh --describe pour voir le leader actuel. Les producteurs réessaient automatiquement.

Utilisez kafka-producer-perf-test.sh pour tester la production :

kafka-producer-perf-test.sh --topic orders --num-records 1000 --record-size 100 --throughput 100 --producer-props bootstrap.servers=broker1:9092

La sortie attendue comprend les enregistrements envoyés et les percentiles de latence. Si les enregistrements envoyés sont 0, corrigez la connectivité ou la configuration.

Boucles de rééquilibrage des groupes de consommateurs

Symptôme : les consommateurs enregistrent fréquemment (Re-)joining group ; le retard augmente ; le traitement s'arrête.

Cause : max.poll.interval.ms dépassé parce que le traitement prend trop de temps ; ou session.timeout.ms trop bas ; ou trop de partitions par consommateur.

Diagnostic : utilisez la description du groupe de consommateurs :

kafka-consumer-groups.sh --bootstrap-server broker1:9092 --describe --group payments-group

Si les membres changent constamment, vérifiez les journaux des consommateurs pour les déclencheurs de rééquilibrage.

Correction :

• Augmentez max.poll.interval.ms pour permettre un traitement plus long : définissez à 600000 (10 minutes).
• Ajustez session.timeout.ms et heartbeat.interval.ms aux conditions du réseau.
• Réduisez le nombre d'enregistrements par interrogation en abaissant max.poll.records.
• Assurez-vous que chaque consommateur gère les partitions de manière appropriée ; utilisez assign au lieu de subscribe si vous avez besoin d'un contrôle précis.

Après avoir modifié la configuration du consommateur, redémarrez les consommateurs et surveillez le retard pendant quelques minutes. Il devrait diminuer et se stabiliser.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle pour gérer systématiquement les erreurs Kafka. Elle suit le modèle observer-modifier-vérifier-récupérer.

1. Inventorier le cluster

• Version Kafka : kafka-topics.sh --version
• Statut du broker : kafka-broker-api-versions.sh --bootstrap-server <broker>:9092
• Statut ZooKeeper ou KRaft : echo stat | nc <hôte-zookeeper> 2181 ou kafka-metadata-quorum.sh --bootstrap-server <broker>:9092 describe --status
• Métadonnées du topic : kafka-topics.sh --describe --topic <nom-du-topic>
• Retard du groupe de consommateurs : kafka-consumer-groups.sh --describe --group <nom-du-groupe>

Enregistrez toutes les sorties et horodatages dans un ticket ou un journal.

2. Identifier le composant défaillant

• Producteur : vérifiez les journaux du producteur pour TimeoutException, RecordTooLargeException, NotLeaderForPartitionException
• Consommateur : vérifiez les journaux du consommateur pour les rééquilibrages, CommitFailedException, OffsetOutOfRangeException
• Broker : vérifiez server.log pour FATAL, ERROR, erreurs de disque
• ZooKeeper/KRaft : vérifiez les expirations de session, les élections de leader, la perte de quorum

3. Effectuer le plus petit changement

• Modifiez une valeur de configuration à la fois
• Utilisez des changements de configuration dynamiques lorsque possible pour éviter les redémarrages
• Documentez les valeurs avant et après
• Préparez une commande de retour en arrière

4. Vérifier le résultat

• Relancez la commande de diagnostic qui a montré le problème
• Confirmez la sortie attendue (par exemple, retard en baisse, aucun journal d'erreur, leader disponible)
• Si le problème persiste, annulez la modification et enquêtez davantage

5. Récupérer et documenter

• Si un changement provoque un incident, suivez votre plan de retour en arrière
• Après résolution, mettez à jour les runbooks et les alertes de surveillance
• Ajoutez le modèle d'erreur à votre base de connaissances avec la correction

Exemple d'entrée de runbook :

Erreur : TimeoutException du producteur sur le topic orders
Cause : Le broker 3 était en panne pour maintenance, le tampon du producteur s'est rempli
Correction : Redémarrez le broker 3, attendez que l'ISR récupère, augmentez delivery.timeout.ms du producteur à 120000
Vérification : kafka-producer-perf-test.sh envoie 1000 enregistrements avec 0 échec
Retour en arrière : Si le nouveau délai provoque une latence plus élevée, revenez à 30000

Conclusion

Les erreurs courantes de Kafka sont gérables lorsque vous les abordez avec un flux de travail discipliné : inventorier la version et l'environnement, observer les symptômes en lecture seule, effectuer le plus petit changement sûr, vérifier le résultat et documenter la récupération. Les exemples de ce guide fournissent des commandes concrètes et des sorties attendues pour les pannes Kafka les plus fréquentes, des pannes de broker aux rééquilibrages de consommateurs.

Choisissez une vérification à faible risque de cet article et pratiquez-la dans un environnement de préproduction avant de faire face à un incident de production. Par exemple, exécutez kafka-consumer-groups.sh --describe --group <votre-groupe> sur un cluster de test et confirmez que vous pouvez interpréter la sortie du retard. Enregistrez l'état actuel avant tout changement et gardez toujours un chemin de retour en arrière.

Une exploitation Kafka fiable rend les pannes visibles, protège les valeurs sensibles, limite les modifications à la ressource prévue et définit la vérification de la récupération avant qu'un incident ne force la décision. Avec ces habitudes, les erreurs courantes de Kafka deviennent des vérifications de routine plutôt que des urgences.