AnsibleByExample

Fix Ansible Handlers Not Running — notify, flush_handlers & Common Pitfalls

intermediateAnsible ErrorAnsible TroubleshootingAnsible HandlersAnsible Best Practices
2026-03-032By Luca Berton

Lesson 1 of 20 in Production Playbooks

Production Playbooks and Troubleshooting — full curriculum
  1. 1. Advanced Playbook Structure & Execution Strategies
  2. 2. Deep Dive: Variable Precedence & Best Practices
  3. 3. Jinja2 Templating Beyond Basics
  4. 4. Advanced Conditionals
  5. 5. Loops Masterclass
  6. 6. Blocks, Rescue, Always (Error Handling)
  7. 7. Handlers Advanced
  8. 8. Change Control: changed_when, failed_when
  9. 9. Tags and Selective Runs
  10. 10. Performance Tuning
  11. 11. Delegation Patterns
  12. 12. Local Actions and Remote Actions
  13. 13. Dynamic Inventory & Runtime Host Management
  14. 14. Includes & Imports (Structuring Large Codebases)
  15. 15. Role Design Patterns
  16. 16. Ansible Galaxy & Collections in Real Projects
  17. 17. Working with APIs (uri + JSON workflows)
  18. 18. Testing and Linting (Quality Gates)
  19. 19. Advanced Debugging Playbook Failures
  20. 20. Capstone: Multi-Stage Deployment
View path overview →

The Problem

You added notify: restart nginx but the handler never runs.

Cause 1: Name Mismatch

# WRONG — names don't match exactly
tasks:
  - name: Update config
    ansible.builtin.copy:
      src: nginx.conf
      dest: /etc/nginx/nginx.conf
    notify: Restart nginx  # Capital R

handlers:
  - name: restart nginx   # lowercase r ← MISMATCH
    ansible.builtin.service:
      name: nginx
      state: restarted

Handler names are case-sensitive. They must match exactly.

Cause 2: Task Didn't Change Anything

Handlers only run when the task reports changed. If the file is already identical:

TASK [Update config] ****
ok: [server]  ← "ok" not "changed" — handler won't fire

Force a change to test:

- name: Touch config to force change
  ansible.builtin.file:
    path: /etc/nginx/nginx.conf
    state: touch
  notify: restart nginx
  changed_when: true  # Force "changed" status

Cause 3: Task Failed Before Handler Ran

Handlers run at the end of the play, not immediately after notify. If a later task fails, handlers are skipped.

# Fix: force handlers to run mid-play
tasks:
  - name: Update config
    ansible.builtin.copy:
      src: nginx.conf
      dest: /etc/nginx/nginx.conf
    notify: restart nginx

  - name: Force handlers now
    ansible.builtin.meta: flush_handlers

  - name: This might fail
    ansible.builtin.command: /opt/risky-script.sh

Or use --force-handlers:

ansible-playbook playbook.yml --force-handlers

Cause 4: Handler in Wrong Section

# WRONG — handler defined as a task
tasks:
  - name: restart nginx
    ansible.builtin.service:
      name: nginx
      state: restarted

# RIGHT — handler in handlers section
handlers:
  - name: restart nginx
    ansible.builtin.service:
      name: nginx
      state: restarted

Cause 5: Listen vs Name

# Using listen for multiple notifications
tasks:
  - name: Update app config
    ansible.builtin.template:
      src: app.conf.j2
      dest: /etc/app/app.conf
    notify: restart app stack

handlers:
  - name: restart app
    ansible.builtin.service:
      name: myapp
      state: restarted
    listen: restart app stack

  - name: restart worker
    ansible.builtin.service:
      name: myapp-worker
      state: restarted
    listen: restart app stack

Debugging Handlers

# Verbose output shows handler notifications
ansible-playbook playbook.yml -vv

# Look for:
# NOTIFIED HANDLER restart nginx
# RUNNING HANDLER [restart nginx]

Conclusion

Handlers not running? Check: exact name match, task actually changed something, no failures before handler execution. Use meta: flush_handlers when you need handlers to run immediately.

All Tutorials