Skip to content

Commit 3f5851a

Browse files
committed
Document callback behaviour when there are no previous Dag runs
1 parent 5abfbd9 commit 3f5851a

3 files changed

Lines changed: 7 additions & 3 deletions

File tree

airflow-core/docs/administration-and-deployment/listeners.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,8 @@ a scheduler restart or when a paused Dag is re-enabled), the scheduler invokes t
7272
``on_intervals_skipped`` listener hook with a
7373
:class:`~airflow.timetables.base.SkippedIntervalsSummary`. This is the listener counterpart to the Dag-level
7474
``on_skipped_intervals_callback``; listeners run synchronously in the scheduler, while the callback
75-
is dispatched to the dag processor.
75+
is dispatched to the dag processor. Like the callback, it does not fire on a Dag's first
76+
automated run (no previous run to compare against).
7677

7778
- ``on_intervals_skipped``
7879

airflow-core/docs/administration-and-deployment/logging-monitoring/callbacks.rst

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,9 @@ to be notified when that happens.
107107

108108
The callback is invoked once per scheduler decision that creates a new scheduled Dag run while
109109
intervals were skipped between the previous automated run and the new run. No Dag runs are
110-
created for the skipped intervals.
110+
created for the skipped intervals. It does not fire on a Dag's first automated run (no previous
111+
run to compare against), even when ``catchup=False`` leaves intervals after ``start_date``
112+
uncreated.
111113

112114
The callback runs in the dag processor (like other Dag-level callbacks), not in the scheduler.
113115
The context mapping contains:

task-sdk/src/airflow/sdk/definitions/dag.py

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -392,7 +392,8 @@ class DAG:
392392
:param on_skipped_intervals_callback: A function or list of functions invoked by the
393393
scheduler when a Dag with ``catchup=False`` advances past one or more scheduled
394394
data intervals without creating Dag runs for them (for example after a scheduler
395-
restart or when a paused Dag is re-enabled). The callback receives a
395+
restart or when a paused Dag is re-enabled). Does not fire on the first automated
396+
run (no previous run to compare against). The callback receives a
396397
:class:`~airflow.sdk.definitions.context.SkippedIntervalsCallbackContext`.
397398
It runs in the dag processor, not in the scheduler.
398399
:param access_control: Specify optional DAG-level actions, e.g.,

0 commit comments

Comments
 (0)