Handler ordering and flush_handlers · Ansible

Two facts about handler execution cause most of the confusion in this part. Neither is obscure, and neither is guessable:

Handlers do not run where they were notified. They run at a flush point, and a play has three of them by default.
Handlers do not run in the order they were notified. They run in the order they were defined in the handlers section.

The second one is the surprise. It is also easy to demonstrate, so this lesson demonstrates it rather than asserting it.

The three flush points

The execution-order lesson established the sections of a play. Handlers attach to them like this:

pre_tasks  →  flush  →  roles + tasks  →  flush  →  post_tasks  →  flush

Anything notified during pre_tasks runs before the first role starts. Anything notified by a role or a task runs after the last task in the play body. Anything notified during post_tasks runs at the very end. A notification cannot cross a flush point backwards, and it does not survive to a later section — it is consumed at the first flush that follows it.

Read-only / Safethe three flush points, executed— Verified on ansible-core 2.21.3 against a local-connection inventory using debug tasks with changed_when: true. Task and handler headers only.

$ ansible-playbook -i inv.ini flush.yml

TASK [A pre_task that changes] *************************************************
changed: [localhost]
RUNNING HANDLER [Pre handler] **************************************************
ok: [localhost]
TASK [First task changes and notifies twice] ***********************************
changed: [localhost]
TASK [Force the queued handlers to run now] ************************************
RUNNING HANDLER [Main handler] *************************************************
ok: [localhost]
TASK [A task after the flush] **************************************************
changed: [localhost]
RUNNING HANDLER [Main handler] *************************************************
ok: [localhost]
TASK [A post_task that changes] ************************************************
changed: [localhost]
RUNNING HANDLER [Post handler] *************************************************
ok: [localhost]

Three things in that output are worth pausing on.

The pre_tasks handler ran before the play body, not at the end. The task in the middle notified Main handler twice in one notify list and the handler ran once — de-duplication is real and it is per flush, not per play, which is why Main handler appears a second time after the later task notified it again. And the explicit meta: flush_handlers produced a handler run in the middle of the tasks section, which is the subject of the second half of this lesson.

Definition order, not notification order

This is the fact that catches people. The handlers section is an ordered list, and that list is the execution order.

Read-only / Safethe ordering test— Three tasks notify C, then A, then B. The handlers are defined A, B, C. Run with debug so nothing is modified.

- name: Handler ordering demonstration
hosts: local
gather_facts: false
tasks:
  - name: Notify the third handler first
    ansible.builtin.debug:
      msg: notify C
    changed_when: true
    notify: Handler C

  - name: Notify the first handler second
    ansible.builtin.debug:
      msg: notify A
    changed_when: true
    notify: Handler A

  - name: Notify the second handler last
    ansible.builtin.debug:
      msg: notify B
    changed_when: true
    notify: Handler B

handlers:
  - name: Handler A
    ansible.builtin.debug:
      msg: A ran
  - name: Handler B
    ansible.builtin.debug:
      msg: B ran
  - name: Handler C
    ansible.builtin.debug:
      msg: C ran

Read-only / Safeexecuted on ansible-core 2.21.3— Notification order was C, A, B. Execution order is A, B, C - the order of the handlers section.

$ ansible-playbook -i inv.ini order.yml

TASK [Notify the third handler first] ******************************************
changed: [localhost]

TASK [Notify the first handler second] *****************************************
changed: [localhost]

TASK [Notify the second handler last] ******************************************
changed: [localhost]

RUNNING HANDLER [Handler A] ****************************************************
ok: [localhost]

RUNNING HANDLER [Handler B] ****************************************************
ok: [localhost]

RUNNING HANDLER [Handler C] ****************************************************
ok: [localhost]

PLAY RECAP *********************************************************************
localhost                  : ok=6    changed=3    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

Notified C, A, B. Executed A, B, C. The handlers list is the schedule.

Where this bites

The case that reaches production looks like this. A role defines two handlers:

handlers:
  - name: Restart the application
  - name: Reload the reverse proxy

Someone reasons “the proxy must come back before the app is restarted, so I will notify the proxy first”. They reorder the notify entries on the tasks. Nothing changes, because the notify order was never the execution order. The fix is to reorder the handlers section.

The failure is quiet: both handlers run, the play is green, and the sequencing that somebody thought they had specified simply is not there. It surfaces as an intermittent restart-order problem that only shows up when both handlers happen to fire in the same run.

Forcing a flush: `meta: flush_handlers`

ansible.builtin.meta with the value flush_handlers runs every handler currently notified for that host, at the point where the meta task appears, and clears the notification set.

Service impact possiblea dependency that needs a flush— The verification task needs the new configuration to be live. Without the flush it would run against the old one, because the reload would not happen until the end of the play.

- name: Deploy and verify the reverse proxy configuration
hosts: webservers
become: true
tasks:
  - name: Deploy the site configuration
    ansible.builtin.template:
      src: site.conf.j2
      dest: /etc/nginx/conf.d/site.conf
      mode: '0644'
    notify: Reload nginx

  - name: Apply the new configuration before anything checks it
    ansible.builtin.meta: flush_handlers

  - name: Confirm the service answers on the new listener
    ansible.builtin.uri:
      url: 'http://127.0.0.1:8443/healthz'
      status_code: 200
    changed_when: false
    retries: 5
    delay: 2

handlers:
  - name: Reload nginx
    ansible.builtin.systemd_service:
      name: nginx
      state: reloaded

This is the honest use of flush_handlers: a later task in the same play depends on the handler having already run. Without the flush, the health check runs against a process still holding the previous configuration, passes, and tells you nothing.

Three properties of the meta task are worth knowing before you rely on it:

It flushes whatever is currently notified, not a named handler. There is no “flush just this one”.
It runs the notified handlers in definition order, exactly as an end-of-section flush does. Forcing an early flush does not let you reorder anything.
It does honour when. Verified on ansible-core 2.21.3: a meta: flush_handlers with when: false reports skipping and the notification survives to the ordinary end-of-section flush. A skipped flush delays handlers; it does not cancel them.

That last point is worth stating positively, because a skipped flush is easy to misread as a suppressed handler. It is not. The handler still runs — just later, at the section boundary, by which time the task that needed it to have run already ran without it.

Under the hood

Handlers are stored as an ordered list per play. Notification adds the resolved handler to a per-host set; the flush iterates the ordered list and runs any entry whose set membership includes the current host.

That iteration is the whole explanation for definition-order execution: the notification set has no ordering to preserve, so the only order available at flush time is the order of the list being walked.

It also explains de-duplication for free. Ten notifications add the same element to a set ten times, and the set has one element. The handler appears once in the walk and runs once.

Because handlers are attached to the play rather than to a role, a role included by two different plays contributes its handlers to each play independently, and the ordering that results is the order in which they were imported into that particular play. Two plays including the same two roles in different orders can execute the same handlers in different orders. If you depend on handler ordering, depend on it within one play and read that play’s assembled handler list rather than reasoning about role boundaries.

What happens if a handler notifies another handler?

It works, and on ansible-core 2.21.3 it works in both directions.

A handler carrying its own notify behaves like any other task: if it reports changed, the named handler is notified. Executed on 2.21.3, a handler defined second that notified a handler defined first still caused the first one to run — after it, in a follow-on pass, not before it.

That is convenient and it is also a trap for readability. A handler chain is a control-flow graph expressed across a list that is executed in definition order, and a reader tracing “what actually restarts when the certificate changes” has to hold the whole graph in their head.

Two links is usually fine. If you find yourself building three, the thing you actually want is a listen topic that several handlers subscribe to, which is the next lesson.

The three flush points

Definition order, not notification order

Forcing a flush: meta: flush_handlers

Knowledge check

Forcing a flush: `meta: flush_handlers`