failed_when: when non-zero is not a failure · Ansible

Ansible’s default rule for a command is simple and frequently wrong: exit code 0 is success, anything else is failure.

That rule matches how most tools behave and mismatches how a useful minority behave. grep returns 1 when it found nothing, which is an answer rather than a fault. A compliance scanner may return 2 for “findings present”, which is the entire reason you ran it. systemctl is-active returns 3 for “inactive”, which may be the state you are checking for.

failed_when is how you tell Ansible what failure means for a specific command. It is the mirror of changed_when, and it has one use case that is more important than all the rest.

Replacing the default rule

The shape is the same as changed_when: an expression evaluated on the controller after the module returns, whose result replaces the module’s failed value.

- name: Check whether the deprecated setting is still present
  ansible.builtin.command: grep -q '^legacy_mode' /etc/app/app.conf
  register: legacy
  changed_when: false
  failed_when: legacy.rc not in [0, 1]

Read the three lines together, because they are one statement:

changed_when: false — grep reads, it does not write.
failed_when: legacy.rc not in [0, 1] — 0 means found, 1 means not found, and both are answers. Anything else — 2 is grep’s “file could not be read” — is a genuine fault.

The not in [...] form is the one to reach for. It states the set of codes you understand, so a code you have never seen still fails loudly. failed_when: legacy.rc == 2 would treat a hypothetical rc 3 as success, which is a promise you did not mean to make.

Afterwards, legacy.rc == 0 is a usable boolean for a later when:.

failed_when preserves the distinction; ignore_errors destroys it

The lazy alternative to the above is:

- name: Check whether the deprecated setting is still present
  ansible.builtin.command: grep -q '^legacy_mode' /etc/app/app.conf
  register: legacy
  ignore_errors: true

This “works” — the play continues. What it has done is declare that no failure of this task matters. A permissions error reading the file, a missing file, a typo in the path: all of them now pass silently, and legacy.rc is some value nobody reasoned about that a later when: will interpret as if it were meaningful.

failed_when says which outcomes are acceptable. ignore_errors says none of them matter. The first is a specification; the second is a shrug, and it shows up in the recap as ignored.

The dangerous inverse: exit 0 while having failed

Everything above is about a command that reports failure when it did not fail. The opposite case is rarer, harder to spot and much more expensive.

Some tools exit 0 unconditionally. Wrapper scripts that end with an echo. Vendor CLIs that print ERROR: to stdout and exit 0 because their author never thought about it. Anything piped through tee. Anything ending in || true.

For those, Ansible’s default rule reports success on a failed operation, and the run goes green:

- name: Push the configuration to the appliance
  ansible.builtin.command: /opt/vendor/bin/push-config --file /etc/vendor/app.conf
  register: push
  changed_when: "'applied' in push.stdout"
  failed_when: >-
    push.rc != 0
    or 'ERROR' in push.stdout
    or 'failed' in push.stderr

Now the task fails when the tool says it failed, regardless of what it told the shell. This is the case where failed_when is not a convenience — it is the only thing standing between you and a green run over a broken change.

The failure that hides behind a pipe

- name: Deploy and log
  ansible.builtin.shell: /opt/app/deploy.sh | tee /var/log/deploy.log

The exit status of a pipeline is the status of its last command, and tee almost always succeeds. deploy.sh can fail catastrophically and this task reports changed and ok.

ansible.builtin.shell runs the command under whatever DEFAULT_EXECUTABLE names, and ansible-config list on 2.21.3 reports its default as /bin/sh — which does not have bash’s pipefail enabled. Either set the executable and the option explicitly, or — better — do not build a pipeline inside a task. Register the result and write the log with a separate task, or let the callback plugin capture the output, which is what it is for.

Writing the condition

Three rules that hold up.

Enumerate what you accept, not what you reject. rc not in [0, 1] survives a tool that gains a new exit code; rc == 2 does not.

A list is joined with and. Same as changed_when — the keyword is typed as a list and a list is a conjunction:

Read-only / Safefailed_when list semantics— Verified on ansible-core 2.21.3. The task ran /bin/false: rc != 0 is true, the stderr condition is false, and the conjunction gives ok.

$ ansible-playbook -i inv2.ini semantics.yml

TASK [failed_when also ANDs a list] ********************************************
ok: [localhost]

      failed_when:
        - c.rc != 0                       # true
        - "'nosuchtext' in c.stderr"      # false  -> and -> not failed

A task that failed on rc and passed on the message did not fail. That is often exactly what you want — “fail only when it exits non-zero and says something we recognise as fatal” — and it is a trap when you meant “or”.

failed_when: false is ignore_errors with extra steps. If the expression is a constant false, you have not specified anything; you have suppressed everything. Write what you mean, and if what you mean is “nothing here can fail”, ask whether the task should be there at all.

Reading the consequences in the recap

Read-only / Safethree failures, none of them counted as failed— Verified on ansible-core 2.21.3. One task failed under ignore_errors, one failed inside a block and was rescued, and a third non-zero exit was absorbed by failed_when: false.

$ ansible-playbook -i inv2.ini vocab.yml

TASK [A non-zero exit that is not a failure] ***********************************
ok: [localhost]

TASK [A real failure that was swallowed] ***************************************
fatal: [localhost]: FAILED! => {"changed": false, "cmd": ["/bin/false"], "msg": "The command exited with a non-zero return code.", "rc": 1}
...ignoring

TASK [Fail inside the block] ***************************************************
fatal: [localhost]: FAILED! => {"changed": false, "cmd": ["/bin/false"], "msg": "The command exited with a non-zero return code.", "rc": 1}

TASK [Recover] *****************************************************************
ok: [localhost] => {
  "msg": "recovered"
}

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

Note the difference between the first and second tasks. Both ran /bin/false. The first, carrying failed_when: false, produced a silent ok with no fatal: line at all. The second, carrying ignore_errors: true, printed the full failure and then ...ignoring.

ignore_errors is at least visible — it leaves the failure in the log and increments ignored. failed_when: false erases it entirely: no message, no counter, nothing. Of the two bad options, the loud one is less bad.

Under the hood

failed_when is evaluated by the task executor after the module returns, in the same phase as changed_when, and it replaces result['failed'].

The evaluation order matters and is worth knowing: the module runs, the result comes back, changed_when is evaluated, then failed_when. This is why a task can end up with "changed": true and FAILED! at the same time — the change was reported before the failure was decided. That combination appears in real logs and confuses people; it is not a bug.

ignore_errors is different in kind. It does not touch failed at all: the result stays failed, and the play iterator declines to remove the host from the play. That is why the failure still prints and still counts under ignored, and it is why a registered result from an ignored task correctly reports failed: true if you check it.

rescue is different again: the failure is real, the host would have left the play, and the block’s rescue section catches it and returns the host to normal execution, counting one under rescued.

What happens if you put ignore_errors on a whole block?

Every task in the block becomes non-fatal, including the ones you had not thought about.

ignore_errors is legal on a block and inherits down to every task inside it, exactly like become. ansible-doc -t keyword ignore_errors on 2.21.3 lists its applies_to as Play, Role, Block, Task and Handler — so it can be set at play level too, which is worse still. A block written to tolerate one expected failure now tolerates all of them: the task that renders the config, the task that validates it, the task that reloads the service.

The same output notes one useful limit: “It does not affect connection errors.” An unreachable host is still unreachable, and ignore_errors: true will not hide it.

The rescue section of a block is almost always the right construct instead. It catches a failure, lets you do something about it — restore a backup, mark the host as needing attention, raise a specific error message — and it records the event as rescued rather than making it disappear.

The error-handling part builds this properly, including why a rescue that only logs is not much better than ignore_errors.

Replacing the default rule

The dangerous inverse: exit 0 while having failed

Writing the condition

Reading the consequences in the recap

Knowledge check