Repository navigation
template variable start_date doesn't exist #62457
Description
Activity
seems new for airflow 3.
in the latest airflow 2 document, there's no
start_datehttps://airflow.apache.org/docs/apache-airflow/2.11.1/templates-ref.html
Analysis of the start_date Inconsistency
I wanted to provide a clear summary of the inconsistency around start_date in the template context.
What Changed in Commit 518287c
The commit “Runtime context shouldn't have start_date as a key (#46961)” removed start_date from the runtime template context produced by get_template_context(). However, the following places were not updated and still reference it:
task-sdk/src/airflow/sdk/definitions/context.py
(This still defines start_date: DateTime in the Context TypedDict)airflow-core/docs/templates-ref.rst
(This still documents {{ start_date }} as an available template field)Because these areas did not get updated, they no longer match runtime behavior.
Current State (Misaligned)
The current behavior looks like this:
Runtime context (get_template_context())
Does not include start_date
This is correct, as the commit intentionally removed it.TypedDict (Context, located in task-sdk/src/airflow/sdk/definitions/context.py)
Still lists start_date
This is incorrect, because the runtime no longer provides it.Documentation (airflow-core/docs/templates-ref.rst)
Still documents {{ start_date }}
This is incorrect, because using it now raises an error.User Impact
Right now, if a user follows the documentation and writes:
{{ start_date }}
they receive:
KeyError: 'start_date'
The only currently valid ways to access it are:
ti.start_date
task_instance.start_dateSo documentation, type hints, and runtime behavior do not match.
Two Possible Fix Approaches
I see two logical directions to resolve this inconsistency. Both are technically valid; the maintainers' intention will decide which is appropriate.
Option A: Remove start_date from TypedDict and Documentation
(Aligns with the intent of commit 518287c)
This requires:
Removing the start_date entry from the Context TypedDict
File: task-sdk/src/airflow/sdk/definitions/context.pyRemoving the reference to {{ start_date }} from the documentation
File: airflow-core/docs/templates-ref.rstThis would make type hints and documentation match the current runtime behavior.
Option B: Add start_date Back to the Runtime Context
(If the project prefers keeping the old template behavior)This would require updating the template context assembly in:
task-sdk/src/airflow/sdk/execution_time/task_runner.py
Specifically, restoring start_date inside the cached template context.
This would make runtime, documentation, and TypedDict consistent again, but it would partially undo commit 518287c.Cool. I believe you already have enough information to create a PR.
Personaly I prefer option A as start_date is already somewhere else in the context. It's not cool have duplicate data.
Apache Airflow version
3.1.7
If "Other Airflow 3 version" selected, which one?
No response
What happened?
the template variable
start_datelisted in document doesn't existan example dag
with a template file
demo.sqlWhat you think should happen instead?
at least two options
a. remove
start_datefrom the template document.dag developer could find start_date from
dag_run.start_dateortask_instance.start_date(the type isdatetime.datetime)b. add
start_date(pendulum.DateTime) into contextHow to reproduce
use the dag in the description.
Operating System
debian
Versions of Apache Airflow Providers
No response
Deployment
Other Docker-based deployment
Deployment details
No response
Anything else?
No response
Are you willing to submit PR?
Code of Conduct