## Introduction Les erreurs courantes d'Apache Airflow et leurs solutions doivent être abordées avec des exemples pratiques pour aider les opérateurs à passer d'un problème observé à un résultat vérifié. Commencez par identifier la version installée, la topologie du déploiement, les prérequis et le composant exact inspecté. Cet article se concentre sur les erreurs courantes d'Apache Airflow pour les développeurs, les consultants DevOps et les équipes techniques de startups. Il relie les corrections Apache Airflow, les messages d'erreur Apache Airflow, le débogage Apache Airflow et le dépannage Apache Airflow à des commandes, des sorties attendues, des signaux d'échec et des décisions de récupération qui correspondent à la technologie sélectionnée. L'objectif est la sécurité opérationnelle : 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. Tout au long de ce guide, nous décomposons le dépannage en quatre phases qui correspondent directement aux sections ci-dessous : - Inventaire de la version et de l'environnement : Connaître votre déploiement. - Parcours de configuration sûr : Modifier une chose à la fois en gardant la récupération à l'esprit. - Vérification et diagnostics : Utiliser des commandes en lecture seule et des journaux pour identifier la cause racine. - Modes de défaillance et récupération : Gérer les classes de défaillance les plus courantes avec des étapes concrètes. Nous fournissons également une liste de contrôle opérationnelle à la fin à garder à portée de main lors d'incidents. ## Inventaire de la version et de l'environnement Avant de pouvoir corriger un problème Apache Airflow, vous devez savoir exactement ce que vous exécutez. Appliquer aveuglément une correction destinée à Airflow 2.6 à un déploiement Airflow 3.0 peut aggraver la situation. L'inventaire de la version et de l'environnement est un instantané structuré, en lecture seule, de votre système. Il documente : - La version exacte d'Airflow. - L'exécuteur utilisé (par exemple, CeleryExecutor, KubernetesExecutor, LocalExecutor). - Le backend de la base de données de métadonnées (PostgreSQL, MySQL, SQLite) et sa version. - La manière dont les DAG sont distribués et synchronisés (git-sync, montages de volumes, pipeline CI/CD). - Les paquets fournisseurs installés et leurs versions (par exemple, apache-airflow-providers-amazon , apache-airflow-providers-google ). - La méthode de déploiement (Docker Compose, chart Helm Kubernetes, bare metal, service géré comme MWAA ou Cloud Composer). ### Pourquoi la version compte : Airflow 2 vs Airflow 3 Airflow 3 a introduit des changements architecturaux significatifs. Le planificateur est divisé en un processeur de DAG et un planificateur, et un nouveau serveur API gère l'API REST. L'ancien processus airflow webserver a disparu. Les commandes et les points de terminaison de vérification de santé diffèrent. Par exemple : - Dans Airflow 2, airflow webserver démarre l'interface utilisateur web. - Dans Airflow 3, vous exécutez airflow api-server et accédez à l'interface utilisateur via celui-ci. Si vous voyez une ModuleNotFoundError ou une KeyError comme 'dag_processor' dans les journaux, vous exécutez peut-être une commande destinée à la mauvaise version majeure. ### Vérifications de santé en lecture seule Commencez toujours par des commandes en lecture seule qui ne modifient pas l'état. Sur Airflow 2.7+ et toutes les versions 3.x, utilisez : airflow version # Exemple de sortie : 2.10.3 airflow info # Affiche l'environnement détaillé : version Python, plateforme, plugins, fournisseurs. Vérifiez la santé des composants critiques sans rien redémarrer. Pour Airflow 3, le point de terminaison de santé unifié est : curl -s http://localhost:8080/api/v2/monitor/health La sortie attendue est un objet JSON avec le statut de chaque composant. Pour un système sain, vous devriez voir quelque chose comme : { "metadatabase": {"status": "healthy"}, "scheduler": {"status": "healthy"}, "triggerer": {"status": "healthy"}, "dag_processor": {"status": "healthy"} } Ne considérez pas un HTTP 200 comme une preuve que tout va bien. Le point de terminaison renvoie 200 même si un composant signale "unhealthy" . Au lieu de cela, analysez le JSON et recherchez les statuts non sains. Pour Airflow 2.x sans le point de terminaison unifié, vérifiez chaque élément : airflow jobs check --job-type SchedulerJob --hostname $(hostname) # Renvoie le code de sortie 0 si le battement de cœur du planificateur est frais. airflow db check # Valide la connectivité de la base de données et le schéma. Si vous utilisez CeleryExecutor, vérifiez également la connectivité du broker : celery -A airflow.executors.celery_executor inspect ping # Attendu : {'celery@worker1': {'ok': 'pong'}} ### Chemins de mise à niveau et migrations Lors de la planification d'une mise à niveau d'Airflow 2.7+ vers Airflow 3.x : - Consultez les notes de version : Chaque version a une liste de changements cassants. Consultez la documentation d'Airflow et les journaux de modifications des fournisseurs. - Sauvegardez la base de données de métadonnées : C'est non négociable. Utilisez pg_dump pour PostgreSQL, mysqldump pour MySQL. - Testez des DAG représentatifs dans un environnement de staging avant de toucher à la production. - Utilisez airflow db migrate après la mise à niveau du code. Cette commande applique les changements de schéma. Ne vous contentez pas de redémarrer les services ; un redémarrage sans migration laissera le schéma de la base de données incompatible et provoquera des plantages du planificateur avec InvalidRequestError ou ProgrammingError . Exemple de commande de migration : airflow db migrate # La sortie se termine par "Database migrating done!" Ne substituez pas un redémarrage à une migration ou à un plan de récupération vérifié. ## Parcours de configuration sûr Les changements de configuration sont une source courante d'erreurs Airflow. Un secret manquant, une faute de frappe dans airflow.cfg ou un paramètre incompatible peut faire tomber tout le pipeline. Le parcours de configuration sûr garantit que les modifications sont délibérées, isolées et réversibles. ### Localisation de la configuration Airflow charge la configuration à partir du premier fichier trouvé dans : - Variable d'environnement AIRFLOW_CONFIG . - airflow.cfg dans le répertoire de travail actuel. - airflow.cfg dans $AIRFLOW_HOME . - Valeurs par défaut dans le code. Pour voir le chemin exact et les paramètres actuels, exécutez : airflow config list Cela affiche tous les paramètres dans un format comme setting = value . Notez que les valeurs sensibles telles que les mots de passe de base de données sont masquées. ### Erreurs de configuration courantes Examinons quelques erreurs de configuration réelles et comment les corriger en toute sécurité. ### 1. sqlalchemy.exc.OperationalError lors de la connexion à la base de données Symptôme : Les journaux du planificateur montrent OperationalError: (psycopg2.OperationalError) could not connect to server: Connection refused . Cause racine : sql_alchemy_conn est mal configuré ou la base de données est en panne. Correction sûre : - Vérifiez la chaîne de connexion. Elle doit être au format postgresql+psycopg2://user:password@host:port/database . - Vérifiez que l'hôte et le port sont joignables. Utilisez nc -zv localhost 5432 (lecture seule). - Si vous utilisez des variables d'environnement, assurez-vous qu'elles sont définies dans l'environnement où le planificateur s'exécute. Exemple d'extrait airflow.cfg : [database] sql_alchemy_conn = postgresql+psycopg2://airflow:airflow@postgres/airflow Après correction, validez avec airflow db check . ### 2. Le planificateur ne peut pas lire les fichiers DAG en raison d'un mauvais dags_folder Symptôme : Les DAG ne sont pas visibles dans l'interface utilisateur. Les journaux montrent FileNotFoundError ou No such file or directory lors de la tentative de lecture de dags_folder . Cause racine : Le chemin dags_folder est incorrect ou l'utilisateur exécutant Airflow n'a pas les permissions. Correction sûre : - Confirmez le chemin absolu. Si vous utilisez Docker, assurez-vous que le volume est monté correctement. - Vérifiez les permissions : ls -ld /opt/airflow/dags doit être accessible par l'utilisateur airflow . - Utilisez airflow dags list-import-errors pour voir les erreurs spécifiques au niveau du fichier. Exemple de commande pour lister les erreurs d'importation : airflow dags list-import-errors # Sortie sans erreur : No data found # Sinon, affiche le nom de fichier et la trace. ### 3. Différences de configuration entre Airflow 2 et Airflow 3 Airflow 3 a déplacé de nombreux paramètres vers une nouvelle section [api_server] . Si vous définissez web_server_port en espérant qu'il fonctionne, il sera ignoré. Utilisez plutôt : [api_server] port = 8080 Consultez toujours la référence de configuration de la version spécifique avant de modifier un paramètre. ### Application sécurisée des changements de configuration - Ne modifiez jamais airflow.cfg directement sur un système en cours d'exécution sans plan . Utilisez une configuration versionnée, des variables d'environnement ou un gestionnaire de secrets. - Modifiez un paramètre à la fois et enregistrez le changement, la raison et l'effet attendu. - Redémarrez uniquement le composant affecté . Dans Airflow 2, si vous modifiez les paramètres du planificateur, redémarrez uniquement le planificateur, pas le serveur web et les travailleurs. - Utilisez airflow config get pour vérifier que la nouvelle valeur est prise en compte avant de redémarrer : airflow config get database sql_alchemy_conn # Attendu : postgresql+psycopg2://airflow:airflow@postgres/airflow ## Vérification et diagnostics Après avoir effectué un changement, ou lors du diagnostic d'un problème, vous devez vérifier l'état et collecter des diagnostics. Cette phase consiste à lire les journaux, vérifier les états des tâches et utiliser les outils de débogage intégrés d'Airflow. ### Affichage des journaux de tâches Airflow stocke les journaux pour chaque instance de tâche. Le moyen le plus simple est via l'interface utilisateur, mais sur un serveur, vous pouvez utiliser la CLI : airflow tasks logs example_dag task_1 2024-01-01 La sortie est le journal complet de cette instance de tâche. Pour suivre les journaux en temps réel : airflow tasks run example_dag task_1 2024-01-01 --local Cela exécute la tâche localement sans planification, ce qui est utile pour le débogage. ### Commandes de diagnostic Voici les commandes clés pour les diagnostics : # Afficher les instances de tâches et leurs états pour une exécution de DAG airflow tasks states-for-dag-run example_dag 2024-01-01T00:00:00+00:00 # Lister les DAG et leur statut airflow dags list # Afficher les détails d'un DAG spécifique airflow dags show example_dag Pour la santé du planificateur, consultez ses journaux. Recherchez des lignes comme : [2024-01-01 12:00:00,000] {scheduler_job.py:701} INFO - Starting the scheduler Si le planificateur ne traite pas les DAG, recherchez des erreurs de parsing, telles que : ERROR - Dag import failed Le journal du planificateur inclura la trace, qui pointe souvent vers la ligne exacte dans votre fichier DAG. ### Utilisation de airflow tasks test pour les essais à sec Avant de déployer un changement, testez une tâche localement avec airflow tasks test : airflow tasks test my_dag my_task 2024-01-01 Cela exécute la tâche dans un processus unique sans toucher au planificateur ni à l'état de la base de données de métadonnées pour l'exécution. C'est un excellent moyen de détecter les erreurs Python, les importations manquantes ou les assertions échouées. ### Analyse directe de la base de données de métadonnées Parfois, vous devez interroger la base de données de métadonnées pour comprendre l'état des tâches. Par exemple, pour trouver toutes les instances de tâches échouées au cours du dernier jour : SELECT dag_id, task_id, execution_date, state FROM task_instance WHERE state = 'failed' AND execution_date >= NOW() - INTERVAL '1 day'; Dans PostgreSQL, connectez-vous via psql -h postgres -U airflow . Dans MySQL, utilisez mysql -h mysql -u airflow -p . Cela peut révéler des modèles : une seule tâche échouant systématiquement peut indiquer un problème de dépendance externe, tandis que de nombreuses tâches dans plusieurs DAG échouant simultanément suggèrent un problème de planificateur ou d'infrastructure. ## Modes de défaillance et récupération Les défaillances d'Airflow se répartissent en catégories prévisibles. Voici les plus courantes, avec symptômes, analyse des causes racines et étapes de récupération. ### 1. Erreurs d'importation de DAG Symptômes : Le DAG n'est pas visible dans l'interface utilisateur ou apparaît comme cassé. airflow dags list-import-errors montre des erreurs. Causes courantes : - Erreur de syntaxe dans le fichier DAG. - Paquet Python manquant (par exemple, ImportError: No module named 'psycopg2' ). - Problème de permission pour lire le fichier. Étapes de récupération : - Exécutez airflow dags list-import-errors pour identifier le fichier et l'erreur exacts. - Corrigez la syntaxe ou la dépendance. - Pour un paquet manquant, installez-le dans l'environnement. Par exemple, pip install apache-airflow-providers-postgres . - Redémarrez le planificateur ou le processeur de DAG. Dans Airflow 2, le planificateur analyse périodiquement les DAG, donc la correction peut être prise en compte automatiquement dans min_file_process_interval (par défaut 30 secondes). Dans Airflow 3, le processeur de DAG peut nécessiter un redémarrage. - Vérifiez avec airflow dags list et assurez-vous que le DAG apparaît sans erreurs d'importation. ### 2. Retards de planification ou exécutions manquées Symptômes : Les exécutions de DAG sont en retard ou ne démarrent jamais. Les journaux du planificateur montrent une utilisation CPU élevée ou des temps d'analyse longs. Causes courantes : - Trop de DAG ou parsing de DAG trop complexe. - Planificateur submergé en raison d'un max_threads élevé ou de ressources insuffisantes. - Inadéquation de fuseau horaire : le calendrier du DAG est défini dans un fuseau horaire qui ne correspond pas à celui du planificateur. Étapes de récupération : - Vérifiez la santé du planificateur : airflow jobs check --job-type SchedulerJob --hostname $(hostname) . - Examinez les journaux du planificateur pour un parsing lent. Activez temporairement le journal de débogage : AIRFLOW__LOGGING__LOGGING_LEVEL=DEBUG . - Optimisez les DAG en déplaçant les calculs lourds hors du code de niveau supérieur. Par exemple, évitez d'établir des connexions à la base de données au moment de la définition du DAG. - Augmentez les ressources du planificateur ou réduisez scheduler.max_threads . - Vérifiez le fuseau horaire du calendrier : Dans le DAG, définissez schedule='0 6 *' avec start_date=datetime(2024,1,1, tzinfo=pendulum.timezone('America/New_York')) . Assurez-vous que le planificateur a le même fuseau horaire ou ajustez. ### 3. Échecs de tâches et reprises Symptômes : L'instance de tâche affiche l'état failed dans l'interface utilisateur. Les journaux montrent une exception. Étapes de récupération : - Récupérez les journaux : airflow tasks logs my_dag my_task 2024-01-01 . - Identifiez la cause racine. Erreurs courantes : - psycopg2.OperationalError : base de données inaccessible. - requests.exceptions.ConnectionError : API externe en panne. - ValueError de la validation des données. - Corrigez le problème sous-jacent. - Effacez l'instance de tâche pour la relancer : airflow tasks clear my_dag --task-regex my_task --start-date 2024-01-01 --end-date 2024-01-01 - Surveillez la relance pour garantir le succès. ### 4. Tâches zombies et exécutions bloquées Symptômes : L'instance de tâche reste dans l'état running indéfiniment, même après le crash du travailleur. Cause racine : Défaillance du travailleur sans nettoyage approprié. Les tâches Celery peuvent devenir zombies si le travailleur est tué. Étapes de récupération : - Dans Airflow 2, le planificateur détecte et tue périodiquement les tâches zombies. Vous pouvez ajuster scheduler.task_queued_timeout et scheduler.task_failure_rate . - Marquez manuellement la tâche comme échouée si elle ne peut pas être tuée : UPDATE task_instance SET state = 'failed', end_date = NOW(), duration = 0 WHERE dag_id = 'my_dag' AND task_id = 'my_task' AND state = 'running'; Soyez prudent avec les mises à jour directes de la base de données ; ayez toujours une sauvegarde. ### 5. Problèmes de base de données de métadonnées Symptômes : Le planificateur plante avec OperationalError ou InterfaceError lors de l'accès à la base de données. Cause racine : Base de données en panne, limite de connexions dépassée ou incompatibilité de schéma. Étapes de récupération : - Vérifiez la connectivité de la base de données : airflow db check . - Si vous utilisez PostgreSQL, vérifiez le nombre de connexions : SELECT count(*) FROM pg_stat_activity; . Si au maximum, augmentez max_connections ou réduisez sql_alchemy_pool_size d'Airflow. - Pour une incompatibilité de schéma après mise à niveau, exécutez airflow db migrate . ### 6. Erreurs de secrets et de connexions Symptômes : Les tâches échouent avec KeyError ou ConnectionNotDefined lors de la tentative d'accès aux connexions. Cause racine : L'ID de connexion n'existe pas dans la base de données de métadonnées ou la variable d'environnement n'est pas définie. Étapes de récupération : - Listez les connexions : airflow connections list . Trouvez le conn_id requis. - S'il est manquant, ajoutez-le via l'interface utilisateur ou la CLI. Pour ajouter une connexion PostgreSQL : airflow connections add 'postgres_default' \ --conn-type 'postgres' \ --conn-host 'postgres' \ --conn-login 'airflow' \ --conn-password 'airflow' \ --conn-port 5432 - Si vous utilisez des variables d'environnement pour les secrets, assurez-vous qu'elles sont définies dans l'environnement du travailleur et du planificateur. Testez avec echo $AIRFLOW_CONN_POSTGRES_DEFAULT . ## Liste de contrôle opérationnelle Gardez cette liste de contrôle à portée de main lors d'incidents. Elle résume la séquence sûre : - Enregistrer l'état actuel - Exécutez airflow version et airflow info . - Notez l'heure et tout changement récent. - Vérifier la santé globale - Airflow 2 : airflow jobs check --job-type SchedulerJob --hostname $(hostname) et airflow db check . - Airflow 3 : curl -s http://localhost:8080/api/v2/monitor/health et inspectez le statut de chaque composant. - Identifier le composant défaillant - Est-ce le planificateur, le serveur web/serveur API, le travailleur ou la base de données ? Utilisez les journaux et les vérifications de santé. - Recueillir les journaux - Pour les échecs de tâches : airflow tasks logs . - Pour les problèmes du planificateur : consultez les journaux du planificateur, généralement dans $AIRFLOW_HOME/logs/scheduler/latest/ . - Vérifier les erreurs d'importation de DAG - airflow dags list-import-errors . - Effectuer une analyse des causes racines - Recherchez des modèles courants : connexion à la base de données, faute de frappe de configuration, dépendance manquante, bug de code. - Appliquer la plus petite correction sûre - Modifiez une variable à la fois. - Préférez une substitution par variable d'environnement ou une copie de sauvegarde du fichier de configuration. - Vérifier la correction - Relancez les vérifications de santé. - Pour une correction de DAG, testez avec airflow tasks test . - Si la tâche a échoué, effacez et relancez : airflow tasks clear --task-regex --start-date --end-date . - Documenter et communiquer - Notez la chronologie de l'incident, la cause racine et la correction dans votre journal d'incidents. - Mettez à jour les runbooks et les alertes si nécessaire. En suivant cette liste de contrôle, vous minimisez les temps d'arrêt et évitez d'introduire de nouveaux problèmes. ## Conclusion Les erreurs courantes d'Apache Airflow et leurs solutions pratiques ne sont utiles que si chaque recommandation est délimitée par version, observable et réversible lorsque la technologie le permet. Copier une commande sans vérifier les prérequis et la sortie attendue n'est pas une procédure opérationnelle. Nous avons couvert les étapes essentielles : inventorier votre environnement, effectuer des changements de configuration en toute sécurité, vérifier avec des diagnostics et récupérer des défaillances courantes. N'oubliez pas de toujours séparer l'observation de l'intervention, protéger les identifiants et documenter les étapes de récupération avant d'en avoir besoin. Comme prochaine étape, choisissez une vérification à faible risque pour les erreurs courantes d'Apache Airflow, enregistrez l'état actuel, exécutez la vérification documentée, comparez le résultat avec le signal attendu et examinez les dépendances telles qu'Apache Spark, NiFi et Apache Hop si elles font partie de vos pipelines. Un flux de travail technique fiable rend les défaillances visibles, protège les valeurs sensibles, limite les modifications à la ressource prévue et définit la vérification de récupération avant qu'un incident ne force la décision.