Apache Airflow 错误码指南：AERR 错误分类、异常类型映射与排障步骤实操手册

Apache Airflow 错误码指南AERR 错误分类、异常类型映射与排障步骤实操手册【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflowAirflow 在 DAG 解析、任务执行、元数据库交互等链路中会抛出多种异常dev/AIRFLOW_ERROR_GUIDE.md为此建立了一套统一的 AERR 错误码体系AERR001–AERR100为每类错误规定了异常类型、面向用户的错误信息、成因描述与初步排查步骤。本文完整继承该指南的 100 条错误码定义并结合仓库中真实的异常类源码task-sdk与airflow-core中的 exceptions 模块交叉印证各异常类型的落地位置帮助你在遇到具体报错时快速定位错误码、按组件维度展开排查。1. Airflow Error Guide 是什么该指南位于仓库的 dev/AIRFLOW_ERROR_GUIDE.md是一份面向排障场景的错误速查手册覆盖 DAG 定义与解析、调度器、执行器/Worker、元数据库、XCom、模板渲染、日志与配置等典型故障域。每条错误记录包含五个关键字段Error CodeAERR 前缀 三位数字编号用于在文档、工单或告警中精确定位某一类错误Exception Type抛出该错误的 Python 异常类型Airflow 自定义异常或 Python 内置异常User-facing Error Message用户/运维在界面或日志中看到的错误文案Description错误成因的简要说明First Steps拿到这条错误后应立即执行的初步排查动作。指南中每条错误还标注了对应的官方文档主题如 dynamic-task-mapping、task-instances、xcoms、scheduler 等本文的表格将文档主题以纯文本形式保留在“相关文档主题”列读者可据此在官方 Airflow 文档中检索相应章节。2. 错误码总表AERR001–AERR100 完整收录2.1 AERR001–AERR034动态映射、XCom、数据库与 Cron 基础错误错误码异常类型用户侧错误信息说明初步排查步骤相关文档主题AERR001AirflowExceptionDynamic task mapping exceeded limit动态映射任务数量超过允许的最大值检查配置中的任务数量上限考虑调高限制或优化映射逻辑dynamic-task-mappingAERR002AirflowExceptionTask instance not found调度器或 Webserver 无法在数据库中找到任务实例确认数据库连接稳定核对元数据库中是否存在该任务实例考虑重跑 DAGtask-instancesAERR003AirflowExceptionTask is in None state任务实例未被赋予正确状态常因执行上下文缺失确保任务配置正确且执行上下文已提供尤其是动态任务与任务依赖dag-run (execution context)AERR004AirflowWebServerExceptionWebserver 502 Bad GatewayWebserver 遇到上游问题或代理请求失败查看 Webserver 日志确认上游系统正常必要时重启 Webserverwebserver (troubleshooting)AERR005KeyErrorKeyError in Variable retrieval请求的 Airflow Variable 在元数据库中不存在检查变量是否存在确认使用正确的数据库核对变量是否在 UI 或代码中定义variablesAERR006PermissionErrorAccess denied for SSH hookSSH hook 无法认证或连接目标服务器核对 SSH 凭据与网络可达性先用本地 SSH 客户端手工测试连接operator/sshAERR007AirflowXComExceptionTaskInstance not recognized in XCom任务的 XCom 条目在元数据库中缺失或损坏检查 XCom 数据是否正确推送排查 DAG 中数据推送逻辑清理损坏的 XCom 条目xcomsAERR008AirflowDatabaseExceptionDuplicate XCom entry detected同一 XCom 键值对被多次写入数据库保证每个任务的 XCom 键值唯一修改 DAG 逻辑避免复用键或覆盖 XComxcoms (avoiding-duplicate-keys)AERR009AirflowDatabaseExceptionError creating database sessionAirflow 无法创建新的数据库会话检查数据库连接配置并确认数据库在运行核对用户权限与最大并发连接数set-up-databaseAERR010AirflowConfigExceptionStrict validation in Dataset URI breaks existing DagsDataset URI 不符合新版本引入的更严格校验规则按新校验规则复查 Dataset URI 格式必要时更新 URIdatasets (uri-validation)AERR011AirflowExceptionFailed to upload logs to remote storage任务日志无法推送到配置的远程存储后端检查远程存储后端配置确认连接凭据正确且后端可达logging (remote-logging)AERR012AirflowDatabaseExceptionCannot connect to airflow database元数据库因网络或配置问题不可达验证到元数据库的网络连接排查配置错误必要时重启 Airflow 组件metadata-databaseAERR013KeyErrorKeyError in retrieving XCom value请求的 XCom 值不存在或定义有误确认 XCom 键值定义正确并在任务间正确传递复核任务执行顺序与参数传递xcoms (pushing-and-pulling)AERR014ImportErrorMissing dependency for KubernetesExecutorKubernetesExecutor 所需依赖未安装确认 KubernetesExecutor 所需依赖全部安装用 pip 或环境管理工具补装缺失包executors/kubernetesAERR015AirflowDagPausedExceptionDag is paused and not runningDAG 处于手动暂停状态不会触发调度运行在 Airflow UI 检查 DAG 状态需要时取消暂停核对 DAG 配置与依赖dag-run (paused-dags)AERR016AirflowTaskTimeoutTask execution delayed indefinitely任务未能在指定超时时间内开始执行复查 DAG 中的任务超时设置必要时调大超时并排查系统性能问题operator (timeouts)AERR017AirflowConfigExceptionCant find executor class配置文件中指定的执行器不被识别或不可用核对airflow.cfg中的 executor 配置确认该执行器已安装且受当前 Airflow 版本支持executors (index)AERR018AirflowConfigExceptionInvalid value in airflow.cfg fileairflow.cfg中存在非法或不支持的值复查airflow.cfg中的错误或不支持取值对照官方配置参考文档修正configurations-refAERR019AirflowCliExceptionAirflow CLI authentication failedCLI 命令无法与 Airflow 后端完成认证检查 CLI 是否具备访问后端的正确凭据确认连接配置与环境变量设置正确cli-and-commands (authentication)AERR020AirflowTriggerExceptionError triggering external API触发外部 API 的 trigger 执行失败检查 API 端点是否可达查看 Airflow 日志中 API trigger 逻辑的错误operator/external-taskAERR021AirflowDatabaseExceptionDatabase deadlock detected多个进程在相互冲突的数据库操作上互相锁住排查数据库死锁与冲突操作优化查询或扩容数据库以避免锁竞争database-optimizationsAERR022PermissionErrorPermission error in KubernetesPodOperatorKubernetesPodOperator 缺少执行所需操作的权限审查 KubernetesPodOperator 配置确保其具备在集群中执行操作所需权限operator/kubernetes (permissions)AERR023AirflowSchedulerExceptionScheduler loop error调度器在主循环中遇到意外状况查看调度器日志中的具体错误信息回顾近期环境或 DAG 变更scheduler (troubleshooting)AERR024AirflowParseExceptionBroken Dag: syntax errorDAG 文件存在语法错误导致无法解析逐行检查 DAG 文件的语法错误并修正使用 linter 或 Python 语法检查器辅助定位dagsAERR025AirflowDatabaseExceptionDagRun state update failed更新 DAG Run 状态写入数据库失败检查数据库连接与权限排查可能阻止状态更新的数据库约束或性能问题metadata-databaseAERR026AirflowTaskTimeoutTask marked as failed due to timeout任务超过了允许的最大执行时间调大 DAG 中的任务执行超时排查任务逻辑低效或外部系统延迟operator (timeouts)AERR027FileNotFoundErrorTask log not found任务日志在本地或远程存储中缺失检查任务日志配置确保日志路径配置正确且可访问核对远程存储权限logging (task-logging)AERR028ImportErrorCannot import module in BashOperatorBashOperator 运行的脚本引用了缺失的 Python 模块确保环境中已安装所有所需 Python 模块检查requirements.txt或虚拟环境operator/bashAERR029AirflowConfigExceptionError loading connections from secret从 Secrets 后端加载连接凭据失败检查 Secrets 后端配置与凭据确认后端可达且在 Airflow 中正确接入security/secretsAERR030AirflowWorkerExceptionWorker not respondingWorker 节点无响应或无法上报状态查看 Worker 节点日志必要时重启 Worker核实调度器与 Worker 间网络连通性workerAERR031AirflowExceptionResource not found in GCP hookGCP hook 无法找到指定资源确认资源在 GCP 中存在检查 GCP 凭据并确认 hook 配置正确google providerAERR032AirflowExecutorExceptionBackend not reachable for CeleryCeleryExecutor 无法连接配置的 Celery 后端检查airflow.cfg中 Celery 后端配置核实网络可达性与 Worker 运行状态executors/celeryAERR033AirflowExceptionInvalid cron expressionDAG 提供的 cron 调度表达式非法或无法解析检查 cron 表达式语法使用 cron 校验工具确认格式有效scheduler (scheduling-dags)AERR034UnpicklingErrorUnpicklingError while running task反序列化数据失败常因 Python 版本不兼容或数据损坏确保 Airflow 及依赖与所用 Python 版本兼容检查并清理损坏数据serialization2.2 AERR035–AERR067Worker、调度器、超时与模板错误错误码异常类型用户侧错误信息说明初步排查步骤相关文档主题AERR035AirflowWorkerExceptionTask instance killed by external system执行期间任务实例被外部系统终止查看外部系统日志确定终止原因修改任务处理逻辑以应对外部终止事件operators (external-task-sensor)AERR036AirflowWorkerExceptionWorker died during task execution处理任务的 Worker 进程崩溃或被终止调查 Worker 日志找出崩溃原因确认 Worker 环境资源充足且配置正确worker (troubleshooting)AERR037AirflowDatabaseExceptionFailed to fetch task state元数据库未返回任务实例的有效状态检查元数据库数据一致性与响应能力排查数据库损坏或配置错误metadata-databaseAERR038ValueErrorCron interval parsing failedDAG 调度间隔的 cron 表达式无法解析复查 DAG 配置中的 cron 表达式用校验工具确认格式正确且受 Airflow 支持scheduler (scheduling-dags)AERR039AirflowSchedulerExceptionScheduler throttled due to excessive DagsDAG 数量过多导致调度器处理过慢而被限流优化 DAG 执行与任务调度检查调度器日志中的性能瓶颈调整调度器设置scheduler (performance)AERR040AirflowDatabaseExceptionDagRun execution_date conflicts数据库中某 DAG Run 的 execution_date 不一致确保 execution_date 定义正确且在任务实例间一致检查时区设置与手动覆盖问题dag-runAERR041AirflowTaskTimeoutTask is stuck in queued state任务一直排队但未被任何执行器领取检查执行器配置确保有足够 Worker 可用核实队列设置与任务路由task-instance (queued)AERR042AirflowParseExceptionError while parsing Dag file调度器在 DAG 文件中遇到语法错误或非法代码复查 DAG 文件的代码错误与非法语法入库前用 Python linter 预检dagsAERR043AirflowDagCycleExceptionTask dependency cycle detected任务依赖构成死循环检查 DAG 中的任务依赖确保无循环引用修改依赖以消除环路dags (task-dependencies)AERR044AirflowTaskExceptionTask failed due to retries exceeded任务用尽重试次数仍未成功调大 DAG 中的重试上限或修改任务逻辑以更好地处理失败场景operator (retries)AERR045ValueErrorValueError in task arguments任务算子被传入了非法或不兼容的参数复查算子参数并确保指定正确对照所用算子的文档核对合法参数operatorAERR046AirflowTaskExceptionTask queue not found任务指定的队列不被执行器识别确保指定队列存在于 Airflow 配置中审查执行器设置确认能处理该队列任务queuesAERR047AirflowSchedulerExceptionExecutor cannot retrieve task instance执行器无法从数据库获取任务实例详情核实数据库连接确认元数据库中存在任务实例详情检查执行器日志task-instance (status)AERR048AirflowWebServerExceptionWebserver connection refusedWebserver 进程未运行或不可访问查看 Webserver 日志重启 Webserver 并确认其可通过配置 URL 访问webserverAERR049AirflowTaskExceptionInvalid return type from PythonOperatorPythonOperator 返回了预期之外的类型确保 PythonOperator 使用的函数返回预期类型复查函数实现的类型正确性operator/pythonAERR050AirflowConfigExceptionConfig error: executor not definedAirflow 配置未指定有效执行器复查airflow.cfg确认 executor 指定正确且已安装、配置得当executors (index)AERR051AirflowExceptionError in task failure hook execution任务定义的失败钩子执行时出错检查失败钩子配置查看任务与钩子日志定位失败原因并解决operator (failure-hooks)AERR052AirflowTemplateExceptionFailed to resolve template variable任务模板化字段存在错误或未定义变量复查任务的模板化字段确保所有变量已定义并在 DAG 中正确传入operators (templating)AERR053AirflowSchedulerExceptionScheduler process killed unexpectedly调度器进程因资源或系统问题被终止调查系统日志中的资源相关问题增加系统资源或调整调度器配置schedulerAERR054AirflowTaskTimeoutTask failed with exit code 1任务脚本或子进程以非零码退出表示失败查看任务脚本或子进程日志中的错误码与成因调试脚本并解决底层问题operator/bashAERR055AirflowDatabaseExceptionTaskInstance already exists in database元数据库中出现了重复的 TaskInstance 记录复查任务实例的调度逻辑避免创建重复条目排查 DAG 调度逻辑问题metadata-databaseAERR056AirflowDatabaseExceptionCould not reach the database元数据库连接性问题常因配置错误核实airflow.cfg中元数据库连接设置确认数据库可访问、网络连通正常metadata-database (troubleshooting)AERR057AirflowExecutorExceptionTask stuck in deferred state使用 deferrable 算子的任务长时间停留在 deferred 状态审查 deferrable 算子配置与执行逻辑确保任务能被正确恢复且无长时间延迟operator/deferrableAERR058AirflowExceptionError loading custom operatorDAG 中自定义算子的导入或定义存在问题检查自定义算子导入路径与可用性确认算子类定义与实例化正确operator (creating-custom-operators)AERR059AirflowTriggerExceptionTrigger timeout for external taskExternalTaskSensor 等待外部任务超时调大 ExternalTaskSensor 超时设置检查外部任务是否延迟并调整 DAG 依赖operator/external-taskAERR060AirflowDagImportExceptionDagBag import errors调度器加载 DAG 文件进 DagBag 时遇到问题检查 DAG 文件的语法或配置错误检查 DagBag 加载过程确保无效 DAG 未被纳入scheduler (dagbag)AERR061AirflowDagNotFoundDag not found in trigger Dag runTriggerDagRunOperator 指定的目标 DAG 不存在核对 TriggerDagRunOperator 中的目标 DAG 名称确认 DAG 存在且拼写正确operator/trigger-dagAERR062AirflowDagCycleExceptionCircular dependencies in DAGDAG 中的任务构成循环依赖审查任务依赖并移除循环引用调整 DAG 结构避免无限依赖循环dags (task-dependencies)AERR063AirflowExceptionError in on_failure_callback for DAGDAG 的 on_failure_callback 抛出异常检查回调函数错误确保其正确处理异常不在任务失败处理中再抛新错误advanced/alertsAERR064AirflowTriggerExceptionTriggerDagRunOperator failedTriggerDagRunOperator 无法触发目标 DAG核对 TriggerDagRunOperator 配置确保目标 DAG 存在且触发参数正确operator/trigger-dagAERR065AirflowTaskExceptionDAG execution failed一个或多个任务出错导致整个 DAG Run 执行失败逐任务查看日志确定失败点审查任务依赖、配置与重试策略dag-run (status)AERR066AirflowSchedulerExceptionScheduler heartbeat failed调度器进程停止发送心跳常因资源问题排查 CPU、内存等系统资源并扩容重启调度器并监控性能schedulerAERR067AirflowConfigExceptionScheduler crashes when passing invalid value to argument in default_argsDAG 的 default_args 中含非法或不兼容参数复查 DAG 定义中的default_args确保所有参数合法且与所用 Airflow 版本兼容dags (default-args)AERR068AirflowApiExceptionHTTP error while connecting to API与外部 API 连接时遇到连接问题或无效响应检查 API 连接设置确认外部服务可达验证 API 返回合法响应operator/http2.3 AERR068–AERR100重试积压、日志、模板与数据库结构错误错误码异常类型用户侧错误信息说明初步排查步骤相关文档主题AERR069AirflowSchedulerExceptionScheduler backlog due to excessive retries过多任务重试导致调度器积压过载调整任务重试逻辑与重试上限审查日志中导致过度重试的模式并优化 DAG 逻辑operator (retries)AERR070AirflowExceptionDAG folder not found指定 DAG 目录不存在或不可访问确保 DAG 目录存在且调度器与 Webserver 可访问检查目录权限与路径dags-directoryAERR071AirflowExceptionMax active tasks for DAG exceededDAG 并发任务数超过配置上限调大 DAG 并发任务数设置或调整依赖以限制并发数scheduler (concurrency)AERR072AirflowExceptionCannot find DAG run in the database指定的 DAG Run 在元数据库中缺失或被删除在元数据库中核实该 Run 是否存在确认未被手动删除或损坏dag-runAERR073AirflowExceptionAirflow CLI not recognizedAirflow CLI 命令未安装或不在 PATH 中确认 Airflow 已正确安装且 CLI 在环境 PATH 中可访问必要时重新安装配置cli-and-commandsAERR074AirflowDatabaseExceptionSQLAlchemy database connection error元数据库连接串非法或不可达检查 Airflow 配置中的连接串确保数据库可达并核对凭据与网络database-setupAERR075PermissionErrorPermission denied for Airflow logsAirflow 无权限读写日志检查日志目录文件权限确保运行 Airflow 的用户具备读写权限loggingAERR076AirflowExceptionTask marked as up for retry without retries available任务被错误标记为待重试但已超出重试上限检查 DAG 中的任务重试配置确认重试次数参数设置正确且确有需要operator (retries)AERR077AirflowConfigExceptionInvalid section in airflow.cfgairflow.cfg含未识别的配置段复查airflow.cfg中所有配置段定义正确且被识别对照官方配置参考核对configurations-refAERR078AirflowExceptionTask dependencies are not met上游依赖未完成导致任务无法启动确保上游任务全部成功完成后再触发本任务审查 DAG 中任务依赖定义task-instanceAERR079AirflowExceptionTask not found in serialized DAG序列化 DAG 中缺少被引用的任务检查 DAG 序列化设置确认所有任务被正确序列化核对任务在 DAG 文件中的定义dags (dag-serialization)AERR080AirflowExceptionWorker node not available执行器找不到合适的 Worker 运行任务检查是否有可用 Worker 节点并核实执行器配置确认 Worker 运行且配置正确executors (index)AERR081ModuleNotFoundErrorPython dependency not installedDAG 所需 Python 包缺失确认运行 Airflow 的环境中已安装所需包用 pip 或虚拟环境管理器补装operator/python (python-packages)AERR082AirflowExecutorExceptionCelery task not acknowledgedCelery 任务未被 Worker 确认接收查看 Celery Worker 日志确定未确认原因确认 Celery 在 Airflow 环境中正确配置并运行executors/celeryAERR083AirflowTaskTimeoutTask duration exceeds timeout任务超过其指定的执行超时时间复查任务执行超时设置必要时调大超时或优化任务以在时限内完成operator (timeouts)AERR084AirflowExceptionError migrating database to Airflow version 2.9.3元数据库迁移出现问题常因 schema 不匹配检查数据库 schema 与迁移日志必要时手工执行数据库迁移或排查连通性兼容问题database-migrationsAERR085AirflowExceptionError writing metrics to statsd无法将指标数据发送到配置的 statsd 服务器核实到 statsd 服务器的连接设置确保 statsd 服务器可达且在 Airflow 中配置正确metricsAERR086AirflowExceptionDAG import timeoutDAG 文件解析耗时过长可能因文件过大或代码低效审查 DAG 文件中的大块或低效代码优化解析考虑将大 DAG 拆小scheduler (dag-parsing)AERR087AirflowTemplateExceptionInvalid template in BashOperator commandBashOperator 的 command 模板存在错误检查 BashOperator 模板语法错误确保占位符与变量已正确定义并在任务上下文中可用operator/bashAERR088AirflowDagCycleExceptionMultiple DAGs with same ID两个或多个 DAG 使用相同 ID 引发冲突确保每个 DAG 有唯一 ID审查 DAG 文件找出重复 ID 并解决冲突dags (dag-id)AERR089AttributeErrorAttributeError in PythonOperatorPythonOperator 的 callable 定义不当或缺少必需属性检查 PythonOperator 的 Python callable确保必需参数与属性均已定义并正确传入operator/pythonAERR090AirflowExceptionError in callback execution for TaskInstance任务定义的失败回调抛出错误审查回调函数错误确认函数定义正确且按预期处理异常advanced/alertsAERR091AirflowTaskTimeoutOperator execution exceeded SLA任务算子运行时间超过其 SLA 约定审查任务执行时长并优化代码使其在 SLA 内完成必要时按任务实际耗时调整 SLAoperator (sla)AERR092AirflowDagNotFoundDAG not found in schedulerDAG 文件未加载进调度器常因解析错误或文件缺失检查 DAG 解析日志错误确保 DAG 文件存在于 DAGs 目录且格式正确scheduler (dagbag)AERR093AirflowExceptionError in email notification for task任务失败的邮件通知无法发送核实 Airflow 中的邮件配置检查 SMTP 服务器配置正确且从 Airflow 实例可达advanced/alerts (email-alerts)AERR094AirflowWebServerExceptionAirflow webserver wont startWebserver 进程启动失败常因配置错误或依赖缺失查看 Webserver 日志错误确保所需依赖全部安装且配置正确webserverAERR095ModuleNotFoundErrorNo module named ... in DAG fileDAG 导入的 Python 模块未安装或不可用用 pip 安装缺失模块或确保该模块在 Airflow 运行环境中可用operator/pythonAERR096AirflowTemplateExceptionMissing template field in operator任务算子缺少必需的模板化字段审查任务算子确保所有必需模板化字段已定义为算子参数补齐缺失字段operators (templating)AERR097AirflowExceptionError syncing DAGs to remote storageDAG 文件与远程存储后端如 S3/GCS同步失败核实到远程存储后端的连接确认凭据配置正确且存储服务可访问storage (remote-storage-backends)AERR098AirflowTaskTimeoutSubprocess in task exceeded timeout任务派生的子进程运行超过允许时间复查子进程配置确保其在任务超时内完成必要时调大超时或优化子进程operator (timeouts)AERR099AirflowDatabaseExceptionInconsistent database schema元数据库 schema 过期或损坏检查数据库 schema 并执行必要迁移确保数据库与当前 Airflow 版本同步database-setupAERR100AirflowExceptionInvalid DAG structureDAG 的依赖或属性定义错误审查 DAG 结构错误确保依赖定义正确且不存在循环依赖dags说明原文档中每条错误还带有指向官方 Airflow stable 文档对应章节的链接按照本文输出规范这里统一以“相关文档主题”纯文本呈现读者可在官方 Airflow 文档中按主题名检索。3. 异常类型与仓库源码的对照印证指南中“Exception Type”列的异常并非全是同名可查的类结合仓库源码可以将其分为三类这一区分在排障时很有用。3.1 核心异常基类AirflowException 及 SDK 异常族从源码结构看Airflow 的异常体系以AirflowException为根其权威定义位于 task-sdk 的异常模块核心仓库再行汇聚。task-sdk/src/airflow/sdk/exceptions.py 中定义了AirflowExceptionL36所有 Airflow 错误的基类AirflowNotFoundExceptionL54请求对象不存在时抛出AirflowDagCycleExceptionL71对应 AERR043/AERR062 的任务依赖环检测AirflowSensorTimeoutL178、AirflowTaskTimeoutL193对应 AERR016/AERR026/AERR041/AERR054/AERR083/AERR091/AERR098 等超时族错误其中AirflowTaskTimeout直接继承自BaseException说明它走的是任务终止路径而非普通异常路径。airflow-core侧的 airflow-core/src/airflow/exceptions.py 在文件头部注释中明确写了一条排障关键约定“Any AirflowException raised is expected to cause the TaskInstance to be marked in an ERROR state”——即任务中抛出 Airflow 异常会把任务实例置为 ERROR 状态这是判断“任务失败根因在 Airflow 框架层还是业务代码层”的起点。该文件还从 SDK 重新导出AirflowException、AirflowNotFoundException、AirflowRescheduleException等并在airflow.sdk不可用时提供镜像的兜底类定义L44–L84保证 as-library 场景下异常语义一致。与错误码直接对应的还有AirflowDagDuplicatedIdExceptionexceptions.py#L107-L117DAG ID 重复时抛出并打印“Ignoring DAG ... also found in ...”与 AERR088Multiple DAGs with same ID的场景完全吻合XComNotFoundtask-sdk/src/airflow/sdk/exceptions.py#L345XCom 取值缺失的框架级异常可与 AERR007/AERR013 的“XCom 缺失/损坏”现象联动分析TaskDeferralError/TaskDeferralTimeouttask-sdk/src/airflow/sdk/exceptions.py#L281-L289deferrable 任务恢复失败的异常对应 AERR057 “Task stuck in deferred state” 的底层成因DagRunTriggerException同文件 L289 附近触发 DAG Run 失败对应 AERR061/AERR064 的 TriggerDagRunOperator 场景。3.2 配置类异常AirflowConfigExceptionAERR010、AERR017、AERR018、AERR029、AERR050、AERR067、AERR077 共 7 条错误的异常类型是AirflowConfigException。该类实际定义在共享配置模块 shared/configuration/src/airflow_shared/configuration/exceptions.py继承自Exception并由 airflow-core/src/airflow/exceptions.py#L31 重新导出供全局使用。这意味着凡是看到配置解析、executor 缺失、非法配置段/取值、default_args传参非法一类错误其抛出点通常都落在配置加载链路应优先核对airflow.cfg与环境变量而非业务 DAG。3.3 内置异常与“分类标签”型条目一部分错误码直接使用 Python 内置异常KeyErrorAERR005/AERR013、ValueErrorAERR038/AERR045、PermissionErrorAERR006/AERR022/AERR075、ImportErrorAERR014/AERR028、ModuleNotFoundErrorAERR081/AERR095、FileNotFoundErrorAERR027、UnpicklingErrorAERR034、AttributeErrorAERR089。这类错误信息本身即指向明确环境依赖、权限、文件路径或序列化兼容性问题排查时无需深究 Airflow 框架内部。需要谨慎表述的一点是表中出现的AirflowDatabaseException、AirflowSchedulerException、AirflowWebServerException、AirflowWorkerException、AirflowExecutorException、AirflowTaskException、AirflowApiException、AirflowXComException等类型名在本次核对的airflow-core/src/airflow/exceptions.py与task-sdk/src/airflow/sdk/exceptions.py主异常定义文件中均未能找到同名类定义共享模块中仅确认了AirflowConfigException。可以推断这些名称在该指南中更多是按组件维度的分类标签数据库类/调度器类/Webserver 类/Worker 类等用于帮助排障者把错误归入对应子系统而非逐一对应可捕获的异常类。实际工程中这些场景下捕获到的具体异常类可能随版本与组件而异应以日志中的真实 traceback 类型为准。4. 按组件维度的排障动线把 100 条错误码按子系统归类后可以形成以下排障动线遇到某类现象时先确定所属组件再按对应错误码执行 First Steps。4.1 元数据库连接、会话与 Schema相关错误码AERR002、AERR008、AERR009、AERR012、AERR021、AERR025、AERR037、AERR040、AERR055、AERR056、AERR072、AERR074、AERR084、AERR099。排查顺序建议先确认连通性AERR012/AERR056/AERR074核对airflow.cfg中的连接串、凭据与网络可达性再看会话与权限AERR009检查数据库是否运行、用户权限与最大并发连接数然后查 Schema 一致性AERR084/AERR099AERR084 明确指向 Airflow 2.9.3 版本的迁移场景检查 schema 与迁移日志必要时手工执行迁移最后看数据层问题AERR008 重复 XCom、AERR021 死锁、AERR040 execution_date 冲突、AERR055 重复 TaskInstance这类问题往往伴随调度逻辑缺陷需要结合 DAG 逻辑复查。4.2 调度器与 DAG 解析相关错误码AERR023、AERR024、AERR033、AERR038、AERR039、AERR042、AERR053、AERR060、AERR066、AERR067、AERR069、AERR070、AERR086、AERR092。典型链路DAG 目录不可达AERR070→ 文件解析失败AERR024/AERR042 语法错误、AERR060 DagBag 导入错误、AERR086 解析超时→ 加载后不被调度器识别AERR092→ 调度器循环异常AERR023/AERR053/AERR066 心跳失败→ 规模性瓶颈AERR039 过多 DAG 限流、AERR069 重试积压。cron 表达式问题AERR033/AERR038通常在解析阶段即可通过 linter 或 cron 校验工具前置发现成本最低。4.3 执行器与 Worker相关错误码AERR014、AERR017、AERR030、AERR032、AERR035、AERR036、AERR041、AERR046、AERR047、AERR050、AERR057、AERR080、AERR082。排查分三层配置层executor 未定义AERR050或找不到执行器类AERR017先核airflow.cfgKubernetesExecutor 依赖缺失AERR014属环境问题运行时层任务滞留 queuedAERR041、队列不存在AERR046、执行器取不到任务实例AERR047重点核实 Worker 数量与队列路由进程层Worker 无响应AERR030、Worker 崩溃AERR036、被外部系统杀进程AERR035、Celery 任务未被 ackAERR082需直接查看 Worker 日志与系统资源。4.4 任务执行超时、XCom、模板与回调相关错误码AERR001、AERR003、AERR007、AERR013、AERR016、AERR026、AERR044、AERR049、AERR051、AERR052、AERR054、AERR057、AERR058、AERR076、AERR078、AERR079、AERR083、AERR087、AERR089、AERR090、AERR091、AERR096、AERR098、AERR099。这是错误码密度最高的区域对应 3.1 节源码中AirflowTaskTimeout、TaskDeferralError/TaskDeferralTimeout、XComNotFound等真实异常。实用顺序先区分“没开始”AERR041 排队、AERR078 依赖未满足、AERR003 状态为 None还是“跑着跑着挂了”超时族 AERR016/AERR026/AERR083/AERR091/AERR098、退出码失败 AERR054再检查数据流XCom 的 AERR007/AERR013/AERR008与渲染层模板族 AERR052/AERR087/AERR096回调类错误AERR051/AERR063/AERR090/AERR093要特别注意回调自身抛错会掩盖原始失败原因需单独审查回调函数。4.5 Webserver、CLI 与配置相关错误码AERR004、AERR018、AERR019、AERR029、AERR048、AERR073、AERR075、AERR077、AERR094。Webserver 侧三类现象——502AERR004、连接拒绝AERR048、无法启动AERR094——排查动作一致看 Webserver 日志 → 核对依赖安装 → 重启验证。CLI 认证失败AERR019与 CLI 不可识别AERR073分别对应凭据配置问题和安装/PATH 问题注意区分。4.6 日志、指标与远程存储相关错误码AERR011、AERR027、AERR075、AERR085、AERR097。共同点是“旁路输出失败”日志上传远程存储失败AERR011、本地/远程日志缺失AERR027、日志目录权限不足AERR075、statsd 指标发送失败AERR085、DAG 同步远程存储失败AERR097。这些错误通常不阻塞任务本身但会导致可观测性缺口排查时优先验证凭据与网络可达性。5. 使用本指南的实践建议先定位组件再对错误码拿到用户侧错误信息后先判断它落在 4.1–4.6 的哪个组件动线再在对应错误码条目中执行 First Steps可显著减少无效排查。以真实 traceback 为准如 3.3 节所述表中部分异常类型名是组件分类标签实际日志中的异常类可能与表内名称不同应以运行环境的真实 traceback 类型和task-sdk/src/airflow/sdk/exceptions.py、airflow-core/src/airflow/exceptions.py中的定义为准。结合版本约束个别条目如 AERR084 的 2.9.3 迁移错误指向特定版本的已知问题场景应用前先确认本地 Airflow 版本与该场景匹配。前置校验降低解析类错误AERR024/AERR042/AERR033/AERR038/AERR060/AERR086 一类解析错误都可以用 Python linter、语法检查器和 cron 校验工具在 DAG 入库前拦截属于成本最低的一类预防措施。本文全部内容基于仓库文件 dev/AIRFLOW_ERROR_GUIDE.md 的 100 条错误码定义源码印证部分可继续深入 airflow-core/src/airflow/exceptions.py、task-sdk/src/airflow/sdk/exceptions.py 与 shared/configuration/src/airflow_shared/configuration/exceptions.py 查看完整异常体系。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考