Support --map-index in airflowctl tasks state by IamJasonBian · Pull Request #68776 · apache/airflow

IamJasonBian · 2026-06-19T21:54:32Z

Description

Adds a tasks state command to airflowctl and supports --map-index so the
state of a specific mapped task instance can be retrieved through the CLI:

airflowctl tasks state --dag-id=example_bash_operator \
  --dag-run-id="manual__..." --task-id=runme_0 [--map-index=N]

Also fixes the airflowctl integration test that exercised this area: it had
invoked the auto-generated taskinstances get command with --dag-id/
--dag-run-id/--task-id flags, which that command does not accept (it takes
positional args), causing argparse to exit 2. The entry now uses tasks state
(flags) to cover the new command, plus a correctly-formed positional
taskinstances get entry so both commands are exercised.

Testing

Set up localhost:8080

Ran below after toggling in UI

airflowctl tasks state
  --dag-id=example_bash_operator
  --dag-run-id="manual__2026-06-19T20:58:0
  8.871418+00:00" --task-id=runme_0 -> SUCCESS and FAIL states

 airflowctl tasks state
  --dag-id=example_bash_operator
  --dag-run-id="manual__2026-06-19T20:58:0
  8.871418+00:00" --task-id=this_will_skip -> SKIPPED

airflowctl tasks state
  --dag-id=example_bash_operator
  --dag-run-id="manual__2026-06-19T20:58:0
  8.871418+00:00" --task-id=nope_task -> not_found

airflowctl tasks state
  --dag-id=example_bash_operator
  --dag-run-id="manual__2026-06-19T20:58:0
  8.871418+00:00" --task-id=runme_0 -> not_found
  --map-index=0

  airflowctl tasks state
  --dag-id=example_bash_operator --dag-run
  -id="manual__2025-10-04T20:38:46+00:00"
  --task-id=runme_0 -> not_found

Reran CI locally

Was generative AI tooling used to co-author this PR?

Yes — Claude Code (Opus 4.8)

Generated-by: Claude Code (Opus 4.8) following the guidelines

Introduce `airflowctl tasks state` to retrieve the state of a task instance by calling GET /api/v2/dags/{dag_id}/dagRuns/{run_id}/ taskInstances/{task_id}. Also add TaskInstancesOperations, help text, and an integration test for the auto-generated taskinstances get command. # Conflicts: # airflow-ctl-tests/tests/airflowctl_tests/test_airflowctl_commands.py

Allow `airflowctl tasks state` to query mapped task instances, matching the legacy `airflow tasks state --map-index` behaviour. When the flag is non-negative the mapped task instance endpoint is called; otherwise the existing unmapped endpoint is used. The `taskinstances get` auto-generated command also gains optional mapped-instance support via the same `map_index` parameter on `TaskInstancesOperations.get`.

The integration test invoked `taskinstances get` with `--dag-id`/`--dag-run-id`/ `--task-id` flags, but that auto-generated command takes positional arguments, so argparse exited with code 2 and the test failed. The flag syntax belongs to the new `tasks state` command, which had no integration coverage at all. Point the entry at `tasks state` (flags) to cover the new command, and add a correctly-formed `taskinstances get` entry using positional args so both commands are exercised.

justinpakzad · 2026-06-20T13:02:16Z

Do you think it's also worth adding a test to the test_operations.py file for the get command? The tests you added only seem to cover tasks state.

@justinpakzad added here, let me know if I'm checking the right things!

Looks good. Just had another look and none of the existing tests in that file test the error path so I think we can remove test_get_not_found_raises.

kk, just removed

Cover the underlying task instances get operation directly — mapped and unmapped endpoints plus 404 handling — not just the tasks state command.

No other tests in the file cover the error path, so drop test_get_not_found_raises and its now-unused ServerResponseError import.

IamJasonBian · 2026-06-22T14:35:54Z

@potluk - can we try a pass at the tests?

++ @jason810496

potiuk · 2026-07-20T10:18:24Z

@IamJasonBian This PR has a few issues that need to be addressed before it can be reviewed — please see our Pull Request quality criteria.

Issues found:

❌ Pre-commit / static checks: Failing: CI image checks / Static checks. Run prek run --from-ref main --stage pre-commit locally to reproduce and fix.

Note: Your branch is 340 commits behind main. Some check failures may be caused by changes in the base branch rather than by your PR. Please rebase your branch and push again to get up-to-date CI results.

What to do next:

Fix each issue listed above.
Make sure static checks pass locally (prek run --from-ref main --stage pre-commit).
Mark the PR as "Ready for review" when you're done.

There is no rush — take your time and work at your own pace. We appreciate your contribution and are happy to wait for updates. If you have questions, feel free to ask on the Airflow Slack.

Note: This comment was drafted by an AI-assisted triage tool and may contain mistakes. Once you have addressed the points above, an Apache Airflow maintainer — a real person — will take the next look at your PR. We use this two-stage triage process so that our maintainers' limited time is spent where it matters most: the conversation with you.

…ate-map-index

The command took required --dag-id/--dag-run-id/--task-id flags, which no other airflowctl command does: the auto-generated commands and core airflow both take identifiers positionally. Users moving between `airflow tasks state` and `airflowctl tasks state` hit a different shape for the same command name. The state value was also printed via str() on a str-mixin enum, which renders as "TaskInstanceState.SUCCESS" rather than "success". Task instances are reached through the hand-written `tasks` group, so the operations class is excluded from command auto-generation to avoid shipping a second, overlapping `taskinstances` surface.

…' into airflowctl-tasks-state-map-index

IamJasonBian · 2026-07-20T14:44:18Z

@potiuk Ready for Review!

AirflowConsole._normalize_data falls through to a bare str() on (str, Enum) fields, using a task_command.py:34 state = getattr(ti.state, "value", ti.state) for this change

Testing

checked

prek run --from-ref main --stage pre-commit

re-ran

pytest airflow-ctl/tests/
pytest scripts/tests/

Resolve conflicts with the new tasks states-for-dag-run command (apache#69366): - keep both 'tasks state' (with --map-index) and 'tasks states-for-dag-run' in a single TASK_COMMANDS group - merge TaskInstancesOperations so it exposes both get() and list() - drop the TaskInstancesOperations exclusions so the auto-generated taskinstances group (get/list) stays available, add help text and an integration-test entry for 'taskinstances get' - regenerate command hashes and tasks/taskinstances help images

Eason09053360 · 2026-09-23T07:08:42Z

Thanks for the patch!
#71206 (already approved) adds the same airflowctl tasks state for #66174, and I test this branch can't land as is (task_state isn't registered in cli_config.py, and test_task_command.py fails at collection), so maybe closing this in favor of #71206 may be simplest.

potiuk

Thanks for working on this, and sorry it sat for a while. Unfortunately #71206 has since added the same airflowctl tasks state command for #66174. It already supports --map-index and --logical-date, handles a missing task instance with a clean error, and is approved with green CI. So I'd suggest closing this one in favour of #71206.

For completeness, this branch also can't land as it stands:

task_state is never registered in airflow-ctl/src/airflowctl/ctl/cli_config.py (there is no tasks state ActionCommand). airflowctl tasks state ... is rejected by argparse, and the new tests in test_task_command.py fail at parse_args.
test_operations.py adds a second class TestTaskInstancesOperations. One already exists earlier in that module, so the redefinition shadows it and its tests stop being collected.
help_texts.yaml ends up with two get: keys under taskinstances:, and the integration-test entry added is a duplicate of the existing taskinstances get line rather than a tasks state case.

If you'd like to help further, a review or a follow-up on #71206 is very welcome. One open idea there is surfacing the API's "task is mapped, pass a map index" detail in the 404 message.

Drafted-by: Claude Code (Opus 5); reviewed by @potiuk before posting

hyungryuk and others added 6 commits May 11, 2026 00:09

Add unit tests for task_state command and TaskInstancesOperations

2440e4b

Merge branch 'main' into airflowctl-tasks-state-map-index

eff9a56

Merge branch 'main' into airflowctl-tasks-state-map-index

f65a04f

IamJasonBian requested review from amoghrajesh, ashb, bugraoz93, dheerajturaga, gopidesupavan, jason810496 and potiuk as code owners June 19, 2026 21:54

boring-cyborg Bot added area:airflow-ctl backport-to-airflow-ctl/v0-1-test kind:documentation labels Jun 19, 2026

Merge branch 'main' into airflowctl-tasks-state-map-index

a036aa4

justinpakzad reviewed Jun 20, 2026

View reviewed changes

Jason Bian and others added 3 commits June 20, 2026 17:41

Add TaskInstancesOperations.get tests for airflowctl

66f21f7

Cover the underlying task instances get operation directly — mapped and unmapped endpoints plus 404 handling — not just the tasks state command.

Merge branch 'main' into airflowctl-tasks-state-map-index

95a68e2

Remove redundant error-path test for task instance get

aa2cbef

No other tests in the file cover the error path, so drop test_get_not_found_raises and its now-unused ServerResponseError import.

IamJasonBian added 4 commits June 22, 2026 23:13

Merge branch 'main' into airflowctl-tasks-state-map-index

64adc52

Merge branch 'main' into airflowctl-tasks-state-map-index

deded12

Merge branch 'main' into airflowctl-tasks-state-map-index

f762b02

Merge branch 'main' into airflowctl-tasks-state-map-index

2b61f1a

IamJasonBian requested a review from henry3260 as a code owner July 3, 2026 02:38

IamJasonBian added 2 commits July 2, 2026 22:39

Merge branch 'main' into airflowctl-tasks-state-map-index

38c47f6

Merge branch 'main' into airflowctl-tasks-state-map-index

0a51fb9

jasonzb and others added 4 commits July 20, 2026 15:55

Merge remote-tracking branch 'upstream/main' into airflowctl-tasks-st…

e562b08

…ate-map-index

Merge branch 'main' into airflowctl-tasks-state-map-index

518dc2d

Merge remote-tracking branch 'origin/airflowctl-tasks-state-map-index…

b0ab7a6

…' into airflowctl-tasks-state-map-index

IamJasonBian requested a review from jscheffl as a code owner July 20, 2026 14:40

IamJasonBian requested a review from justinpakzad July 20, 2026 14:41

jasonzb and others added 5 commits July 22, 2026 11:50

Merge branch 'main' into airflowctl-tasks-state-map-index

18bf937

Merge branch 'main' into airflowctl-tasks-state-map-index

075e0d4

Merge branch 'main' into airflowctl-tasks-state-map-index

790d9c4

Merge branch 'main' into airflowctl-tasks-state-map-index

aa482d1

potiuk reviewed Oct 4, 2026

View reviewed changes

Navigation Menu

Support --map-index in airflowctl tasks state - #68776

Support --map-index in airflowctl tasks state#68776
IamJasonBian wants to merge 25 commits into
apache:mainfrom
IamJasonBian:airflowctl-tasks-state-map-index

IamJasonBian commented Jun 19, 2026 •

edited

Loading

Uh oh!

justinpakzad Jun 20, 2026

Uh oh!

IamJasonBian Jun 20, 2026 •

edited

Loading

Uh oh!

justinpakzad Jun 21, 2026

Uh oh!

IamJasonBian Jun 22, 2026

Uh oh!

IamJasonBian commented Jun 22, 2026 •

edited

Loading

Uh oh!

potiuk commented Jul 20, 2026

Uh oh!

IamJasonBian commented Jul 20, 2026 •

edited

Loading

Uh oh!

Eason09053360 commented Sep 23, 2026

Uh oh!

potiuk left a comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

IamJasonBian commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Testing

Was generative AI tooling used to co-author this PR?

Uh oh!

justinpakzad Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

IamJasonBian Jun 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

justinpakzad Jun 21, 2026

Choose a reason for hiding this comment

Uh oh!

IamJasonBian Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

IamJasonBian commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

potiuk commented Jul 20, 2026

Uh oh!

IamJasonBian commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Testing

Uh oh!

Eason09053360 commented Sep 23, 2026

Uh oh!

potiuk left a comment

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

IamJasonBian commented Jun 19, 2026 •

edited

Loading

IamJasonBian Jun 20, 2026 •

edited

Loading

IamJasonBian commented Jun 22, 2026 •

edited

Loading

IamJasonBian commented Jul 20, 2026 •

edited

Loading