Skip to content

Conversation

@tstrilka
Copy link
Contributor

Summary

This PR adds a new listener hookspec on_task_instance_skipped that is called when a task raises AirflowSkipException.

Related issue: closes #59370

Motivation

The current listener interface provides hooks for:

  • on_task_instance_running - when a task starts
  • on_task_instance_success - when a task succeeds
  • on_task_instance_failed - when a task fails

But there is no hook for when a task is skipped via AirflowSkipException. This gap prevents listener implementations from handling self-skipping tasks.

Scope & Limitations

Important: This hook is called only when a task raises AirflowSkipException during execution — i.e., when a task has actually started and then skips itself.

This hook does NOT cover tasks skipped by:

  • Trigger rules (e.g., upstream failures)
  • BranchPythonOperator (tasks not in the selected branch)
  • ShortCircuitOperator
  • Manual state changes via UI/API
  • Scheduler-level decisions

For comprehensive skip tracking across all skip types, use DAG-level events (on_dag_run_success/on_dag_run_failed) which include AirflowStateRunFacet with the complete tasksState map.

Changes

File Description
airflow-core/src/airflow/listeners/spec/taskinstance.py Added on_task_instance_skipped hookspec
task-sdk/src/airflow/sdk/execution_time/task_runner.py Call listener in finalize() when state is SKIPPED
task-sdk/tests/task_sdk/execution_time/test_task_runner.py Added test for skipped listener

Follow-up

OpenLineage provider implementation will be submitted in a separate PR after this is merged.

Testing

  • Added unit test test_task_runner_calls_listeners_skipped that verifies the listener is called when a task raises AirflowSkipException

^ Add meaningful description above
Read the Pull Request Guidelines for more information.
In case of fundamental code changes, an Airflow Improvement Proposal (AIP) is needed.
In case of a new dependency, check compliance with the ASF 3rd Party License Policy.
In case of backwards incompatible changes please leave a note in a newsfragment file, named {pr_number}.significant.rst or {issue_number}.significant.rst, in airflow-core/newsfragments.

Copy link
Contributor

@kacpermuda kacpermuda left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, this will definitely help listeners to correctly "see" how the task finished it's execution, after they receive an information about task start. Left a few suggestions to improve the docstring.

Co-authored-by: Kacper Muda <mudakacper@gmail.com>
@shahar1 shahar1 merged commit 24f27d9 into apache:main Jan 3, 2026
98 checks passed
@boring-cyborg
Copy link

boring-cyborg bot commented Jan 3, 2026

Awesome work, congrats on your first merged pull request! You are invited to check our Issue Tracker for additional contributions.

henry3260 pushed a commit to henry3260/airflow that referenced this pull request Jan 3, 2026
Co-authored-by: Kacper Muda <mudakacper@gmail.com>
stegololz pushed a commit to stegololz/airflow that referenced this pull request Jan 9, 2026
Co-authored-by: Kacper Muda <mudakacper@gmail.com>
@tstrilka tstrilka deleted the add-on-task-instance-skipped-v2 branch January 12, 2026 12:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add on_task_instance_skipped listener hookspec

4 participants