Ansible handler never runs after task rename because notify still points at the old name

2026-11-13 · 3 min read

Ansible handler never runs after task rename because notify still points at the old name

A deploy finishes with failed=0, CI goes green, and the service keeps running the old config. The task that writes the config reports changed, but the restart handler never executes. The usual cause is a rename: someone changed the handler task’s name from restart nginx to reload nginx, while every notify: still says restart nginx. Ansible matches notifications by name, not by module or file, so the old string no longer points at anything [link needed]. That is an ansible handler not fired after rename — and it is easy to miss because the play can still succeed while the handler is skipped.

Why the rename silently breaks the handler

A notify: value is a string. Ansible resolves it against handler names and listen topics [link needed]. Rename the handler and the old notify: becomes an unmatched notification. Depending on the Ansible version and context, you may get a warning, but the play does not fail just because a notification found no handler [link needed]. The changed task remains changed, the handler stays queued nowhere, and the host keeps stale state.

This is not limited to one file. Notifications can live in roles, included task files, or separate playbooks. Renaming the handler in one place without updating all callers turns a safe refactor into a partial outage.

ansible handler not fired after rename: what to check first

Before changing anything, compare handler names with notification strings. A simple search is enough:


grep -RIn --include='*.yml' --include='*.yaml' -E 'notify:|name:' .

Look for handler names that appear in notify: but no longer exist under handlers:. Also check listen: if the handler uses it. Do this before rerunning the play, because a rerun may show no change and hide the problem: if the config task is already marked changed, only a new change will notify the handler.

Fix a broken rename safely

1. Pick the canonical handler name. Prefer the one that describes the final action, e.g. reload nginx, not the old action.

2. Update the handler name and every notify: in the same commit. Include role callers and included files, not just the current playbook.

3. If external playbooks or roles still notify the old name, add listen: restart nginx to the renamed handler as a compatibility alias [link needed]. Remove it only after callers are updated.

4. Run ansible-playbook --syntax-check and inspect task names with --list-tasks [link needed].

5. Test on staging by making a real config change. Confirm the handler appears as RUNNING in verbose output, not just that the play returns failed=0.

6. Search again for the old name. If no caller remains, delete the listen alias.

The key is step 2: rename the handler and its notifications atomically. A handler rename is an interface change.

When NOT to do this

Do not rename a handler that is effectively a public interface for other teams’ playbooks unless you control their notifications too. Keep the existing name and change only the module arguments, or add a listen alias and treat the old name as supported. Also avoid renaming when several unrelated tasks intentionally converge on one broad handler; first map every caller, then rename once.

Checklist

If a handler seems to “randomly stop,” check for this ansible handler not fired after rename pattern before debugging modules. The fix is usually a name mismatch, not the service.