Airflow Branching: Skipped Tasks That Failed the DAG

Branching looks like the simplest thing in Airflow: if this, run that task; else, run the other. Then the nightly DAG went red at a join task — while every task that actually ran was green.

The grid view told the story. One branch executed. The other was skipped — by design. And the join task, which inherited the default trigger rule all_success, decided a skipped task is as good as a failed one. Red DAG, green graph.

Here's BranchPythonOperator, the skip state, and the trigger rules that decide whether your graph continues. Then it hands you the join patterns that survive skips and the debug flow for skipped graphs.

The default trigger rule is a landmine in any branching DAG. Learn to disarm it before your join goes red at 2 AM.

1. Branching with BranchPythonOperator

BranchPythonOperator wraps a callable that returns the task_id of the next task to run. Airflow then executes that path and skips the rest of the branch. One return value, one path — that contract matters.

The branch callable is plain Python: any condition, any input, any upstream data you pass via op_args. The logic stays testable outside Airflow entirely.

Our payments DAG routes large orders to manual_review and everything else to auto_approve. The untaken side becomes skipped. That skip is about to become the whole story.

The docs bless two return shapes beyond a single task_id: a list of task_ids or task_group_ids, which follows several paths at once, and None, which skips every downstream task. Whatever you return must point to a task directly downstream of the branch — a stale id means the intended path silently never runs.

from airflow.decorators import dag, task
from airflow.operators.python import BranchPythonOperator, PythonOperator
from pendulum import datetime


@dag(schedule="@daily", start_date=datetime(2026, 8, 1), catchup=False, tags=["payments"])
def payments_workflow():
    def choose_payment_path():
        if getattr(context_placeholder, "amount", 0) > 10000:
            return "manual_review"
        return "auto_approve"

    branch = BranchPythonOperator(
        task_id="choose_payment_path",
        python_callable=choose_payment_path,
    )
    auto_approve = PythonOperator(task_id="auto_approve", python_callable=lambda: print("approved"))
    manual_review = PythonOperator(task_id="manual_review", python_callable=lambda: print("reviewed"))

    branch >> [auto_approve, manual_review]


payments_workflow()

2. The Skip State and How It Propagates

Skipped is a terminal state for that task instance — the task had nothing to do. It's not success, and it's not failure. It's a third thing, and every rule downstream has to decide what it means.

Skips cascade. When a task is skipped, its downstream tasks evaluate their trigger rules against the actual states; under all_success they skip too. That's how one untaken branch can grey out half the graph.

Read the grid view with that in mind: grey means "decided not to run," not "broke." The question is always whether the task after the grey one can live with it.

3. Trigger Rules: The Full Table with Production Meaning

A trigger rule decides when a task may start after its upstream tasks finish. The default is all_success — right for linear pipelines, quietly fatal for anything with branches.

The table below is the reference. The three you'll actually use: all_success for linear chains, none_failed for joins, all_done for teardown and notifications. one_failed and all_failed exist for alerting and rollback fan-ins.

One nuance the docs bury: when an upstream can't run because its own upstream failed, it's upstream_failed, not failed — and all_done still counts it. Learn the states before you learn the rules.

Two edge cases decide real incidents. First, when an all_success task sees both a skipped and a failed upstream, its final state depends on which non-successful state the scheduler evaluates first — a failure landing in the same evaluation period wins. Second, none_failed_min_one_success proves nothing when nothing ran: if every upstream is skipped, the join is skipped too, because 'no failure' is not 'data produced'.

4. Join-Task Patterns That Survive Skips

The join is where branches reunite, and it's where the incident lived. With the default all_success, a skipped arm fails the join. The fix pattern: trigger_rule="none_failed" — run when no upstream failed, regardless of skips.

When the joined data itself is required — at least one branch must have produced something — use none_failed_min_one_success. That's the join rule that turns "nothing broke" into "something actually ran."

The rest of the pattern is placement: the join is one explicit task, named for the merge, with a rule written in code and reviewed like a dependency.

from airflow.decorators import dag, task
from airflow.operators.python import BranchPythonOperator, PythonOperator
from pendulum import datetime


@dag(schedule="@daily", start_date=datetime(2026, 8, 1), catchup=False, tags=["payments"])
def payments_workflow():
    def choose_payment_path():
        return "auto_approve"

    branch = BranchPythonOperator(task_id="choose_payment_path", python_callable=choose_payment_path)
    auto_approve = PythonOperator(task_id="auto_approve", python_callable=lambda: print("approved"))
    manual_review = PythonOperator(task_id="manual_review", python_callable=lambda: print("reviewed"))
    notify = PythonOperator(task_id="notify_ops", python_callable=lambda: print("notified"))

    branch >> [auto_approve, manual_review]
    [auto_approve, manual_review] >> notify

    reconcile = PythonOperator(
        task_id="reconcile_payments",
        python_callable=lambda: print("reconciled"),
        trigger_rule="none_failed",  # survives the skipped branch
    )
    notify >> reconcile


payments_workflow()

5. Debugging Skipped Graphs

A red join with all-green upstreams is a rule problem, not a code problem. Verify before you fix: check the states of every upstream of the join, then re-render what the branch callable actually returned.

airflow tasks states prints the whole run's states in one shot — you'll see success, skipped, and the red join side by side. airflow tasks render shows the params the task really ran with, including the branch callable's inputs.

The discipline that ends these incidents: never fix a skipped-graph failure by reading code. Read states first, then rules, then code.

# The state of every task in one run
airflow tasks states payments_workflow 2026-07-15

# What the branch callable actually returned
airflow tasks render payments_workflow choose_payment_path 2026-07-15

# Clear and re-run just the join after a rule change
airflow tasks clear payments_workflow --task-regex reconcile_payments

6. When Branching Hides Design Problems

Branching is a runtime decision inside one DAG. If your branch arms produce different data products, different schedules, or different owners, the branch is hiding a design problem — those are two DAGs.

Airflow 3 makes the split natural: each DAG triggers the next via assets, so the decision point becomes an event instead of an if/else. The graph stays honest.

Also know your cousins: ShortCircuitOperator skips the entire downstream chain when its condition is false — a whole-DAG gate, not a fork. That's a different tool for a different job (deep dive in the conditional-execution article).

7. The Rule That Keeps Joins Green

The postmortem produced three standing rules. First: every join task declares its trigger rule explicitly — none_failed for joins, all_done for teardown, all_success only for true linear chains. Defaults are not decisions.

Second: every branching DAG ships with a verified skip scenario. Run it in dev, force each branch, and read the grid view until you've seen the skipped path come out green.

Third: when the join goes red again — and it will, somewhere — read states, then rules, then code. The fix is usually one line. Finding it is a discipline.