Handlers across role boundaries · Ansible

Everything else about a role is scoped. Its defaults lose to the inventory, its vars are entered and left, its templates/ directory only affects lookups inside it.

Handlers are not. roles/webapp/handlers/main.yml is loaded into the parent play’s handler list, alongside the play’s own handlers and every other role’s. One flat namespace, keyed by name, with no role prefix and no warning on collision.

Two roles that each define a handler called restart nginx are two definitions of one name. Notifying it runs one of them. Not necessarily yours.

The collision, executed

Two roles. ra changes a config file and notifies restart nginx; its own handlers file defines that name. rb also defines a handler called restart nginx — a different one, restarting a different unit — and does nothing else in this play.

# roles/ra/tasks/main.yml
- name: role A changes config
  ansible.builtin.debug: {msg: A-config}
  changed_when: true
  notify: restart nginx

# roles/ra/handlers/main.yml
- name: restart nginx
  ansible.builtin.debug:
    msg: "ROLE-A handler ran"

# roles/rb/handlers/main.yml
- name: restart nginx
  ansible.builtin.debug:
    msg: "ROLE-B handler ran"

- hosts: web
  roles:
    - ra
    - rb

Read-only / Saferole A notified; role B answered— Executed against ansible-core 2.21.3 with debug handlers standing in for service restarts. Role A notified restart nginx and role B's handler is the one that ran. No warning was emitted.

$ ansible-playbook -i inventory.ini collide.yml

TASK [ra : role A changes config] **********************************************
  "msg": "A-config"

TASK [rb : role B does nothing interesting] ************************************
  "msg": "B-noop"

RUNNING HANDLER [rb : restart nginx] *******************************************
  "msg": "ROLE-B handler ran"

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

Read the handler line: RUNNING HANDLER [rb : restart nginx]. Role A’s task notified, role B’s handler ran, and role A’s handler never executed at all. The run reported success.

In production, with real service modules behind those names, that is a config change to service A followed by a restart of service B. Service A keeps serving its old configuration — so the change appears to have been applied and did nothing — and service B takes an unexplained restart during a maintenance window nobody scheduled for it.

Why the obvious diagnosis is wrong

The symptom is “the config change did not take effect”. The obvious diagnosis is that the handler did not fire — a missing notify, a task that reported ok instead of changed, a play that ended before handlers flushed.

All three are real causes and none of them is this one. The handler did fire. The recap shows changed=1. The run output contains a RUNNING HANDLER block. Everything an operator normally checks says the mechanism worked.

The only evidence is the role prefix on the handler line, and it is a three-character difference in a line people read as a heading. Grep the run output rather than skimming it:

ansible-playbook -i inventory.ini site.yml | grep 'RUNNING HANDLER'

Which one wins

The later definition replaces the earlier one for that name. Roles are loaded in the order the play lists them, so the last role to define a name is the one that gets notified — regardless of which role did the notifying.

That ordering dependence is the part that makes this hard to catch. Reorder the roles: list for an unrelated reason and the behaviour changes. The review that approved the reorder saw two role names swap places, not a different service restarting.

Fix one: `listen` topics

listen: gives a handler an additional name that is explicitly a topic — something other content notifies without knowing which handler answers.

# roles/ra/handlers/main.yml
- name: restart nginx
  ansible.builtin.debug:
    msg: "ROLE-A handler ran"
  listen: reload web tier

# roles/ra/tasks/main.yml
- name: role A changes config
  ansible.builtin.debug: {msg: A-config}
  changed_when: true
  notify: reload web tier

Read-only / Safenotify by topic, with the colliding names left in place— Executed. Both roles still define a handler named restart nginx. Role A notifies the topic instead, and role A's handler runs.

$ ansible-playbook -i inventory.ini collide.yml

RUNNING HANDLER [ra : restart nginx] *******************************************
  "msg": "ROLE-A handler ran"

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

Topics are many-to-many by design: several handlers may listen to one topic and all of them run. That makes listen the right interface when a change should trigger work in more than one role — “the certificate changed” ought to reload nginx and haproxy, and neither role should have to know the other exists.

It is the weaker fix for the collision itself, though, because the colliding names are still there for the next person to notify by accident.

Fix two: namespace the names

The fix that removes the problem rather than routing around it is the naming discipline from Part XIII lesson 7, applied to handlers:

# roles/ra/handlers/main.yml
- name: ra restart nginx
  ansible.builtin.debug:
    msg: "ROLE-A handler ran"

Read-only / Safeprefixed names cannot collide— Executed. Role A's handler is named ra restart nginx, so there is no shared name to contend for.

$ ansible-playbook -i inventory.ini collide.yml

RUNNING HANDLER [ra : ra restart nginx] ****************************************
  "msg": "ROLE-A handler ran"

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

The line reads redundantly — ra : ra restart nginx — and that redundancy is the price of a name that cannot be claimed by somebody else’s role. Use the role name as the prefix and the redundancy is at least predictable.

Use both. Prefix every handler name so nothing can collide, and add a listen: topic for the handlers that other roles legitimately need to trigger. The prefix protects the implementation; the topic is the interface.

Auditing an estate you inherited

Collisions are cheap to find and worth finding before an incident does it for you:

Read-only / Safehandler names defined more than once across roles— Reads role handler files and reports any name defined by more than one role. Touches nothing.

grep -rhoP '^-\s+name:\s+\K.*' roles/*/handlers/*.yml \
| sed 's/[[:space:]]*$//' \
| sort | uniq -d

Anything printed is a name two or more roles define. For each one, decide which role owns it, prefix the others, and re-run.

Then check the notify side, because a handler defined once can still be notified from a role that did not mean this one:

Read-only / Safewhich role notifies which name— Lists every notify in every role with its file, so cross-role notifications are visible. Read-only.

grep -rn 'notify:' roles/*/tasks/ | sed 's|roles/||'

Under the hood

When a play is built, each role’s handlers/main.yml is parsed and its handlers are appended to the play’s handler list. They keep a reference to the role they came from — which is why the output prints rb : restart nginx — but the name is stored flat, with no role qualification.

Notification is a name lookup against that flat list. notify: restart nginx searches for a handler whose name or whose listen topics match the string. There is no notion of “the handler belonging to the role that notified”, because the notifying task and the handler are related only by a string.

Handlers also run at the end of the play — or at each meta: flush_handlers, or at the end of each serial batch — rather than at the end of the role. That is the same flat-list consequence viewed from the time axis: there is one handler queue per play, not one per role, so a role cannot rely on its handlers having run before the next role starts. If a role needs its restart to happen before subsequent work, it must flush explicitly.

The design is deliberate. It is what allows a play-level handler to be notified from inside a role, and a role’s handler to be notified from the play, which is genuinely useful. The cost is that names are a global namespace and nothing enforces uniqueness in it.

What happens if you notify a handler name that no handler defines?

The play fails, at run time, when the notification is evaluated — not at parse time, and not silently:

[ERROR]: The requested handler 'no such handler' was not found in either
the main handlers list nor in the listening handlers list

That is the good case, and it is worth knowing because it means a typo in a notify: is loud. The dangerous case is the opposite one: a notify: that finds a handler, just not the one the author meant. There is no version of that which errors, because from Ansible’s point of view the lookup succeeded.

Which is why prefixed names are worth their ugliness. A typo in notify: ra restart nginx almost certainly matches nothing and fails; a typo in notify: restart nginx in an estate where four roles define it has a fair chance of matching the wrong thing and succeeding.

One caveat for anyone auditing: a handler is only reachable if some task notifies it. A handler defined in a role and never notified is dead code that grep will still report, so read the notify side before renaming anything.