Camunda 7 – Boucle Multi-Instance qui ne se termine pas Causes racines & solutions (guide production)

Introduction

L’un des problèmes les plus frustrants en production avec Camunda 7 est une activité Multi-Instance (MI) qui ne se termine jamais.

Symptômes typiques

Toutes les instances semblent finies, mais le processus n’avance pas
La tâche parente reste active indéfiniment
Aucun message d’erreur clair dans les logs
Instance bloquée en production

👉 Dans la grande majorité des cas, ce n’est pas un bug du moteur, mais un problème de modélisation ou de données.

Ce guide explique :

Le fonctionnement interne des Multi-Instances
Pourquoi une MI reste bloquée
Les causes racines les plus courantes
Les solutions et préventions éprouvées

Cette architecture est couramment utilisée dans les environnements microservices modernes.

👉 environnements microservices modernes

Rappel rapide : comment fonctionne une Multi-Instance (Camunda 7)

Une activité Multi-Instance :

Crée plusieurs exécutions (parallèles ou séquentielles)
Suit des compteurs internes :
- nrOfInstances
- nrOfCompletedInstances
Se termine uniquement quand la condition de complétion est satisfaite

Règle simplifiée


nrOfCompletedInstances == nrOfInstances

👉 S’il reste une seule exécution active, la MI ne se termine jamais.

🔷 Diagramme BPMN – Multi-Instance

Repères visuels

Trois barres verticales → MI parallèle
Trois barres horizontales → MI séquentielle
Les caractéristiques MI définissent :
- la collection
- la variable élément
- la condition de complétion (optionnelle)

Cause n°1 : Collection incorrecte ou nulle

Problème

L’expression de collection retourne :

null
une liste vide
un type inattendu


${users}

Mais à l’exécution :


users = null

Résultat

Zéro ou partielle création d’instances
Compteurs incohérents
La MI ne progresse pas

✅ Solution

✔ Valider la collection avant la MI


${users != null ? users : []}

✔ Préparer les données en amont de l’activité MI

Cause n°2 : Une instance ne se termine jamais

Problème

Une instance :

attend sur une User Task
échoue dans une Service Task
reste bloquée par un système externe

Résultat

La MI parente attend indéfiniment
Aucun log d’erreur évident

✅ Solution

✔ S’assurer que chaque chemin se termine
✔ Ajouter des Boundary Events :

Error
Timer
✔ Gérer explicitement les retries

Cause n°3 : Condition de complétion incorrecte

Problème

Condition personnalisée risquée :


${nrOfCompletedInstances == nrOfInstances}

Mais :

une instance est sautée
une autre échoue silencieusement

Résultat

La condition n’est jamais vraie.

✅ Solution

✔ Éviter les conditions personnalisées si possible
✔ Laisser Camunda gérer la complétion par défaut
✔ Sinon, protéger les cas limites

Cause n°4 : Modification de la collection pendant l’exécution

Problème

La collection MI est modifiée pendant que la MI tourne :

éléments retirés
collection remplacée

Résultat

Désynchronisation des compteurs internes
MI bloquée

✅ Solution

✔ Considérer la collection MI comme immuable
✔ Ne jamais la modifier après le démarrage de la MI

Cause n°5 : Asynchrone mal positionné

Problème

Async Before / Async After placé au mauvais endroit.

Résultat

Exécutions fragmentées
Signal de complétion non propagé

✅ Solution

✔ Utiliser l’asynchrone avec parcimonie
✔ Éviter async after sur les MI sauf nécessité
✔ Tester sous charge

Cause n°6 : External Task non complétée

Problème

Le worker externe :

récupère la tâche
exécute la logique
n’appelle jamais complete()

Résultat

L’instance MI reste active à vie

✅ Solution

✔ Toujours appeler complete()
✔ Gérer crashs et redémarrages
✔ Configurer retries et timeouts

Cause n°7 : MI séquentielle + gestion d’erreur absente

Problème

En MI séquentielle, la première erreur bloque la suite.

Résultat

Les instances suivantes ne démarrent jamais
La MI ne se termine pas

✅ Solution

✔ Ajouter des Error Boundary Events
✔ Décider clairement :

arrêter au premier échec
continuer malgré l’erreur

Comment debugger une MI bloquée en production

Checklist pas à pas

Ouvrir l’arbre d’exécution (Cockpit)
Vérifier :
- nrOfInstances
- nrOfCompletedInstances
Identifier l’exécution bloquée
Inspecter :
- variables
- External Tasks
- User Tasks
Vérifier les retries asynchrones

Checklist Multi-Instance « production-safe »

✔ Collection non nulle et valide
✔ Collection immuable
✔ Chaque instance se termine ou échoue proprement
✔ External Tasks complétées systématiquement
✔ Boundary Events présents
✔ Condition de complétion simple ou par défaut
✔ Stratégie claire pour MI séquentielle

Anti-patterns fréquents 🚨

❌ Modifier la collection MI à l’exécution
❌ Conditions de complétion complexes
❌ Absence de timeout / gestion d’erreur
❌ Appels externes bloquants
❌ Supposer que la MI se termine « toute seule »

Question d’entretien (très fréquente)

Q : Pourquoi une Multi-Instance ne se termine pas alors que toutes les tâches semblent finies ?
R : Parce qu’au moins une exécution reste active ou que la condition de complétion n’est jamais satisfaite.

Conclusion

Une Multi-Instance qui ne se termine pas est presque toujours un problème de modélisation ou de données, pas un défaut de Camunda.

Dans 90 % des cas, la cause est :

une instance bloquée
une collection invalide
une logique de complétion non sécurisée
une gestion d’erreur manquante

👉 Traitez la Multi-Instance comme une exécution distribuée : chaque instance doit finir.

💼 Support professionnel disponible

Si vous rencontrez des problèmes sur des projets réels liés au développement backend d’entreprise ou à l’automatisation des workflows, je propose des services de conseil payants, de débogage en production, de support projet et de formations ciblées.
Les technologies couvertes incluent Java, Spring Boot, PL/SQL, Azure, ainsi que l’automatisation des workflows (jBPM, Camunda BPM, RHPAM), DMN/Drools.
📧 Contact: ishikhanirankari@gmail.com | info@realtechnologiesindia.com
🌐 Website: IT Trainings | Digital lectern | Digital rostrum | Digital metal podium

🎥 Learn IT with Shikha on YouTube

Prefer learning through videos? Watch practical tutorials on Kafka, Camunda, Alfresco, Java, Spring Boot, Microservices and Enterprise Architecture.

▶ Subscribe to Learn IT with Shikha on YouTube