This is an automated email from the ASF dual-hosted git repository.
amoghrajesh pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 081db6f5ef5 Document that a mapped task state store index is
positional (#76283)
081db6f5ef5 is described below
commit 081db6f5ef5415565441b3dff17d0302e571b49a
Author: Amogh Desai <[email protected]>
AuthorDate: Mon Nov 16 10:11:08 2026 +0530
Document that a mapped task state store index is positional (#76283)
---
airflow-core/docs/core-concepts/task-state-store.rst | 16 ++++++++++++++++
1 file changed, 16 insertions(+)
diff --git a/airflow-core/docs/core-concepts/task-state-store.rst
b/airflow-core/docs/core-concepts/task-state-store.rst
index b7483380b0d..9bda390e163 100644
--- a/airflow-core/docs/core-concepts/task-state-store.rst
+++ b/airflow-core/docs/core-concepts/task-state-store.rst
@@ -295,6 +295,22 @@ Mapped tasks
When a task is dynamically mapped (``task.expand(...)``), each map index has
its own task state store namespace. ``clear()`` clears only the current index's
store.
+.. warning::
+
+ The map index is positional, not an identity: index ``N`` names whatever
item happens to sit at
+ position ``N`` in the expanded input, and the upstream task may return its
items in a different
+ order on a rerun. If the upstream list changes between attempts
+ (an insertion, a deletion, a reordering), index ``N`` names a different
item than it did before.
+
+ Clearing a task instance discards its state by default, so the next
attempt starts over and this
+ does not arise. It matters when state outlives the re-expansion: if you
clear with
+ ``keep_task_state``, or use one of the clear paths that still keep state
unconditionally (see
+ :doc:`resumable-tasks`), index ``N`` reads the state written by whatever
item was at index ``N``
+ on the previous attempt. Nothing detects the mismatch and the task still
reports success. In the
+ `External job resumption`_ pattern this means reconnecting to a job
submitted for a different item.
+
+ Only keep task state across a clear of a mapped task when the expanded
input is unchanged.
+
To wipe state across all map indices of a task, use the :doc:`Core API
</administration-and-deployment/task-and-asset-state-store>` (e.g. via the UI
or CLI) after the task group has finished.
.. code-block:: python