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

Reply via email to