Report task failure causes without changing retries by 1fanwang · Pull Request #73350 · apache/airflow

1fanwang · 2026-09-18T17:48:20Z

Kubernetes can stop a healthy task without an application exception, but Airflow's failure listeners have no shared category for why it failed. Platform integrations must interpret backend-specific text to route the failure.

This implements AIP-97 Task Failure Classification. Workers and executors report an optional failure kind and diagnostic reason to infrastructure listeners. Failure metrics carry bounded category labels, and logs retain the available cause. Kubernetes classification requires documented disruption evidence; an OOM kill, worker loss or bare eviction reason remains unclassified.

Ordinary retries, clears and Dag callback context stay unchanged. This adds no configuration, schema change or replacement-attempt accounting.

Related: #66405 is the combined prototype; this PR contains only classification and reporting.

Testing Done

Current Linux/PostgreSQL runtime proof

The complete runnable workflow, fixture, and observed output cover 6f7fa704122c6263be59eba6af4bb5d4264d1997 on pinned base b6538c32c8b1cdcb7b818e174a8b09d69ae18ad6.

The run used Linux, Python 3.12, PostgreSQL, the source checkout's locked Breeze tooling, and the recorded public CI image digest. From the Airflow checkout at that commit, with its locked Breeze tooling installed, fetch the exact fixture and run:

set -euo pipefail
SOURCE_DIR="$(pwd)"
FIXTURE="$(mktemp -d)"
gh gist clone 2e63de24c4b14ec4e76e9d73b5e7c304 "$FIXTURE" -- --config url.https://gist.github.com/[email protected]:
git -C "$FIXTURE" checkout 47dd89a08499744b971e579cb12f8deaed2f34e9
mkdir -p dev/aip97-classification/dags dev/aip97-classification/plugins
(
  cd "$FIXTURE"
  cp run.sh "$SOURCE_DIR/dev/aip97-classification/"
  cp classification_readiness.py "$SOURCE_DIR/dev/aip97-classification/dags/"
  cp classification_listener.py "$SOURCE_DIR/dev/aip97-classification/plugins/"
)
breeze ci-image pull --python 3.12 --github-repository apache/airflow
breeze shell --python 3.12 --backend postgres --github-repository apache/airflow \
  --mount-sources all --skip-image-upgrade-check --skip-environment-initialization \
  --tty disabled --answer no -- '
    set -euxo pipefail
    export GIT_CONFIG_COUNT=1
    export GIT_CONFIG_KEY_0=safe.directory
    export GIT_CONFIG_VALUE_0=/opt/airflow
    export AIRFLOW_HOME=/tmp/aip97-classification
    export AIP97_EVIDENCE_DIR=/opt/airflow/dev/aip97-classification/evidence
    export AIP97_EXPECTED_SOURCE_SHA=6f7fa704122c6263be59eba6af4bb5d4264d1997
    export EXPECTED_DB_DIALECT=postgresql
    bash /opt/airflow/dev/aip97-classification/run.sh
  '

The fixture migrated the database, executed real task bodies through the Task SDK and in-process Execution API, and compared loaded source bytes with the pinned commit. Its read-only task-state checks observed:

Scenario	Listener category	Final state	Attempt / retry allowance
Application exception	`application`	`failed`	1 / 0
Execution timeout	`timeout`	`failed`	1 / 0
One configured retry	`application` on the first attempt	`success`	2 / 1

Raw runtime observations

RuntimeError: classification readiness application failure
AIP97_CALLBACK {"cause_in_context": false, "state": "failed", "task_id": "application", "try_number": 1}
AIP97_LISTENER {"kind": "application", "reason": null, "task_id": "application", "try_number": 1}
airflow.sdk.exceptions.AirflowTaskTimeout: Timeout, PID: 2013
AIP97_CALLBACK {"cause_in_context": false, "state": "failed", "task_id": "timeout", "try_number": 1}
AIP97_LISTENER {"kind": "timeout", "reason": null, "task_id": "timeout", "try_number": 1}
RuntimeError: classification readiness application failure
AIP97_CALLBACK {"cause_in_context": false, "state": "up_for_retry", "task_id": "retry", "try_number": 1}
AIP97_LISTENER {"kind": "application", "reason": null, "task_id": "retry", "try_number": 1}
AIP97_CALLBACK {"cause_in_context": false, "state": "success", "task_id": "retry", "try_number": 2}
airflow dags test exit code: 1

The CLI exits 1 because two controls deliberately fail. The wrapper returns 0 only after checking the states, attempts, listeners, callbacks, loaded source, and actual database dialect.

This is current-source Linux/PostgreSQL CLI evidence, not a new live Kubernetes, Celery, or AWS run. The record identifies its retained raw observations, omitted host-specific setup/footer text, and normalized workspace paths.

Historical proof

The earlier Linux/PostgreSQL record remains tied to bb9a387bfdb8803e957ad6a91691962fef49578d on 63b615b252589ef49b8504f2dbe2942b543ec896. Its expected upstream test-isolation failure is a separate diagnostic, not a passing runtime suite.

The earlier macOS/SQLite CLI proof remains tied to 513ac64704e7e8b78e0123c54c82ec9b7fbf4e03.

The Linux/PostgreSQL and live Kubernetes/DogStatsD proof remains tied to 863bc207d6a052a4f5d0573ead077e803c79664f against 257fe6e85112580547374b6e6d6e5b5576155536. Its complete fixture, receipts, and raw observations retain those exact source labels.

Local source review completed.

Was generative AI tooling used to co-author this PR?

Yes, GitHub Copilot CLI

Generated-by: GitHub Copilot CLI following the guidelines

Read the Pull Request Guidelines for more information. Note: commit author/co-author name and email in commits become permanently public when merged.
For fundamental code changes, an Airflow Improvement Proposal (AIP) is needed.
When adding dependency, check compliance with the ASF 3rd Party License Policy.
For significant user-facing changes create newsfragment: {pr_number}.significant.rst, in airflow-core/newsfragments. You can add this file in a follow-up commit after the PR is created so you know the PR number.

Expose known worker and executor causes to infrastructure listeners and telemetry while preserving ordinary retry and clear behavior. Signed-off-by: 1fanwang <[email protected]>

potiuk · 2026-09-25T20:23:37Z

Hello @1fanwang - thank you for your contributions to Apache Airflow!

The Airflow community has introduced a limit of 5 open pull requests at a time for contributors without write access to the repository. You currently have 34 open pull requests, so - as a one-time step of introducing the limit - we closed the ones where maintainers have not engaged yet:

Report failure causes and bound infrastructure replacements #66405 - Report failure causes and bound infrastructure replacements
Honor AirflowFailException raised inside on_retry_callback #66781 - Honor AirflowFailException raised inside on_retry_callback
Emit OpenTelemetry spans from airflow CLI entry points #66789 - Emit OpenTelemetry spans from airflow CLI entry points
Preserve sensor start_date when scheduler advances reschedule to queued #66790 - Preserve sensor start_date when scheduler advances reschedule to queued
Reuse the resumable core for TriggerDagRunOperator's durable wait #68955 - Reuse the resumable core for TriggerDagRunOperator's durable wait
Let TriggerDagRunOperator own its execution via a new accessor #69135 - Let TriggerDagRunOperator own its execution via a new accessor
Add resumable_job.reconnect_failure metric for failed reconnects #70653 - Add resumable_job.reconnect_failure metric for failed reconnects
Allow configuring the collation of asset name columns #71249 - Allow configuring the collation of asset name columns
Fix task_instance_history downgrade failing under the PyMySQL driver #71258 - Fix task_instance_history downgrade failing under the PyMySQL driver
Correct the retry_db_transaction docstring about provide_session #71311 - Correct the retry_db_transaction docstring about provide_session
Show worker pod logs for tasks that failed before writing any log #71566 - Show worker pod logs for tasks that failed before writing any log
Reconnect Synapse Spark batches on task retry #72368 - Reconnect Synapse Spark batches on task retry
Reconnect Azure Data Factory pipelines on task retry #72399 - Reconnect Azure Data Factory pipelines on task retry
Prevent duplicate Anthropic batches on task retry #72400 - Prevent duplicate Anthropic batches on task retry
Reconnect AWS Batch jobs after worker crashes #72413 - Reconnect AWS Batch jobs after worker crashes
Reconnect Airbyte sync jobs after task retries #72414 - Reconnect Airbyte sync jobs after task retries
Reconnect Data Fusion pipelines after task retries #72415 - Reconnect Data Fusion pipelines after task retries
Prevent duplicate OpenAI batches on task retry #72416 - Prevent duplicate OpenAI batches on task retry
Recover Dataproc jobs after worker crashes #72417 - Recover Dataproc jobs after worker crashes
Recover Athena queries after worker crashes #72419 - Recover Athena queries after worker crashes
Reconnect Cloud Batch jobs on task retry #72420 - Reconnect Cloud Batch jobs on task retry
Prevent duplicate ECS submissions on task retry #72421 - Prevent duplicate ECS submissions on task retry
Recover Databricks SQL statements after task retries #72422 - Recover Databricks SQL statements after task retries
Reconnect dbt Cloud runs after worker crashes #72423 - Reconnect dbt Cloud runs after worker crashes
Restore missing serialized Dags without a full reparse #72927 - Restore missing serialized Dags without a full reparse
Report task failure causes without changing retries #73350 - Report task failure causes without changing retries

These pull requests stay open because maintainers are already engaged in them - they count towards your limit:

Add durable option to TriggerDagRunOperator to reconnect on retry #68936 - Add durable option to TriggerDagRunOperator to reconnect on retry
Let deferrable tasks reconnect without polling #68952 - Let deferrable tasks reconnect without polling
Keep database failures from looking like missing secrets #71307 - Retry transient database errors in the metastore secrets backend
Return each attempt's own URL from operator extra links #71522 - Return each attempt's own URL from operator extra links
Return 404 when a DagRun disappears during task API writes #72907 - Return 404 instead of 500 when DagRun is missing in Execution API
Edge: Return 404 for missing task logs #72908 - Edge: Return 404 for missing task logs and emit failed job metrics
Edge: Return 400 instead of 500 on invalid worker version #72925 - Edge: Return 400 instead of 500 on invalid worker version
Return 404 for task-state writes after a Dag run is deleted #72926 - Return 404 for task-state writes after a Dag run is deleted

This is not a judgement of you or of your changes. We never told contributors before that opening many pull requests at once was a problem, so there is nothing to feel bad about - and nothing is lost: your branches, commits and the review history stay where they are.

What we ask you to do is to make your first prioritization decision: choose which of the pull requests above matter most to you, and reopen them (up to 5 open at a time, including the ones still open) with the "Reopen pull request" button or gh pr reopen <PR_NUMBER> --repo apache/airflow. Reopen the ones you are ready to follow through - keep them rebased, respond to review comments and fix failing checks.

While your pull requests are waiting for review, the most valuable thing you can do is help in other ways - reviewing other contributors' pull requests, helping with issues, and taking part in the discussions on the devlist and Slack.

Why we introduced the limit, what it means for you and how to reopen or restore a pull request is explained in https://github.com/apache/airflow/blob/main/contributing-docs/32_open_pull_request_limit.rst.

Drafted-by: Claude Code (Opus 5); reviewed by @potiuk before posting

1fanwang requested review from XD-DENG, amoghrajesh, ashb, bugraoz93, choo121600, dheerajturaga, ephraimbuddy, henry3260, hussein-awala, jason810496, jedcunningham, jscheffl, kaxil, o-nikolas, pierrejeambrun, potiuk, rawwar and shubhamraj-git as code owners September 18, 2026 17:48

boring-cyborg Bot added area:API Airflow's REST/HTTP API area:Executors-core LocalExecutor & SequentialExecutor area:providers area:scheduler area:task-sdk kind:documentation provider:cncf-kubernetes Kubernetes (k8s) provider related issues labels Sep 18, 2026

1fanwang force-pushed the 1fannnw/aip97-classification branch from 6edb01f to 513ac64 Compare September 22, 2026 07:55

1fanwang mentioned this pull request Sep 22, 2026

Report failure causes and bound infrastructure replacements #66405

Closed

1 task done

1fanwang force-pushed the 1fannnw/aip97-classification branch from 513ac64 to bb9a387 Compare September 22, 2026 19:33

Report task failure causes without changing retries

6f7fa70

Expose known worker and executor causes to infrastructure listeners and telemetry while preserving ordinary retry and clear behavior. Signed-off-by: 1fanwang <[email protected]>

1fanwang force-pushed the 1fannnw/aip97-classification branch from bb9a387 to 6f7fa70 Compare September 23, 2026 06:22

potiuk added the closed because of open PR limit Closed as a one-time step of introducing the open pull request limit label Sep 25, 2026

potiuk closed this Sep 25, 2026

Navigation Menu

Repository navigation

Report task failure causes without changing retries - #73350

Report task failure causes without changing retries#73350
1fanwang wants to merge 1 commit into
apache:mainfrom
1fanwang:1fannnw/aip97-classification

1fanwang commented Sep 18, 2026 •

edited

Loading

Uh oh!

potiuk commented Sep 25, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

1fanwang commented Sep 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Testing Done

Current Linux/PostgreSQL runtime proof

Historical proof

Was generative AI tooling used to co-author this PR?

Uh oh!

potiuk commented Sep 25, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

1fanwang commented Sep 18, 2026 •

edited

Loading