Error Handling and Blocks

Analogy categoryAnalogies

Handling Task Failures in Ansible

By default, when a task fails on a given host, Ansible marks that host as failed and removes it from the remaining tasks in the current play, so subsequent tasks in that play simply skip that host while other, unaffected hosts continue normally. The ignore_errors: true directive can override this per task, letting the play continue on that host even after a failure, but it should be used sparingly since blindly ignoring errors can mask a real problem that causes a much worse failure several tasks later.

🏏

Cricket analogy: Default failure halting is like an umpire stopping play the instant a serious injury occurs on the field, rather than letting the match continue as if nothing happened, unless the physio explicitly waves it off as minor.

block / rescue / always

The block keyword groups related tasks so a shared when condition or ignore_errors setting applies to the whole group at once instead of being repeated on every individual task, which keeps playbooks cleaner and less error-prone. A rescue section attached to that block runs only if a task inside the block fails, giving Ansible a try/except-like pattern where you can log the failure, attempt a remediation, or trigger a rollback; an always section runs unconditionally regardless of whether the block succeeded, failed, or was rescued, which is the right place for cleanup work like removing a temporary file or sending a completion notification.

🏏

Cricket analogy: block/rescue/always is like a team's rain-delay protocol: the block is the planned session of play, rescue is the reserve-day plan triggered only if rain washes out the session, and always is the post-match pitch cover routine that happens no matter how the day went.

yaml

- name: Deploy application with rollback safety net
  block:
    - name: Copy new release artifact
      ansible.builtin.copy:
        src: app-release.tar.gz
        dest: /opt/app/releases/app-release.tar.gz

    - name: Run database migration
      ansible.builtin.command: /opt/app/bin/migrate.sh
      register: migration
      changed_when: "'Applied' in migration.stdout"

    - name: Restart application service
      ansible.builtin.systemd:
        name: myapp
        state: restarted
  rescue:
    - name: Log the failure details
      ansible.builtin.debug:
        msg: "Deploy failed on task '{{ ansible_failed_task.name }}': {{ ansible_failed_result.msg }}"

    - name: Roll back to previous release
      ansible.builtin.command: /opt/app/bin/rollback.sh
  always:
    - name: Notify deployment channel
      community.general.slack:
        token: "{{ slack_token }}"
        msg: "Deploy finished on {{ inventory_hostname }} (rescued: {{ ansible_failed_task is defined }})"

failed_when, changed_when, and Custom Failure Conditions

failed_when lets you override Ansible's default success/failure detection, which is essential for command and shell modules where a nonzero return code isn't necessarily a real problem, or conversely where a zero return code might still represent a logical failure your playbook actually cares about, such as a script that exits 0 but prints 'ERROR' to stdout. changed_when works the same way but controls whether a task reports as changed rather than failed, which matters for accurate Tower/AWX job history and for any downstream logic (like notification-on-change) that depends on knowing whether a task actually did something.

🏏

Cricket analogy: failed_when is like a match referee deciding that a specific outcome, such as a no-ball call, counts as a failure for review purposes even though play technically continued, overriding the default assumption that continuing play means everything was fine.

Inside a rescue block, the ansible_failed_task and ansible_failed_result variables are automatically available, letting you log or branch on exactly which task failed and what error it produced — useful for building targeted remediation logic rather than a generic catch-all.

Overusing ignore_errors: true across a playbook without explicitly checking result.failed on downstream tasks can let a genuinely broken deployment silently proceed all the way through to production-affecting steps, defeating the safety that Ansible's default fail-fast behavior provides.

By default, a failed task removes that host from the rest of the current play, while unaffected hosts continue.
ignore_errors: true overrides default failure handling per task but should be used sparingly to avoid masking real problems.
block groups related tasks so a shared when condition or ignore_errors applies once instead of per task.
rescue runs only if a task inside the paired block fails, giving Ansible a try/except-like pattern.
always runs unconditionally regardless of success, failure, or rescue outcome, ideal for cleanup and notifications.
failed_when and changed_when override Ansible's default success/failure and changed detection based on custom conditions.
ansible_failed_task and ansible_failed_result are available inside rescue blocks for targeted logging and remediation.