when expressions that hold up · Ansible

when decides whether a task runs on a host. It is the smallest piece of control flow Ansible has and it is responsible for a disproportionate share of the incidents in this course, because the characteristic failure of a when is not an error. It is a task that quietly does not run.

ansible-core 2.21 changes a large part of that, and changes it for the better. This lesson covers the mechanics, then the 2.21 behaviour, then the traps that are still traps.

`when` is raw Jinja

The value of when is a Jinja expression, evaluated directly. It does not go through the templating braces:

Read-only / Safethe syntax, and the thing everyone does once— The first form is correct. The second wraps an expression in braces where an expression is already expected.

# Correct.
- name: Install with apt
ansible.builtin.package:
  name: chrony
when: ansible_facts.os_family == 'Debian'

# Wrong. The braces are already implied.
- name: Install with apt
ansible.builtin.package:
  name: chrony
when: "{{ ansible_facts.os_family == 'Debian' }}"

The second form has historically been the source of a specific bug: the braces render the expression to the string "True" or "False", and both of those strings are truthy, so the task runs unconditionally. That is precisely the failure mode 2.21 now refuses to have.

A list under when is ANDed:

when:
  - ansible_facts.os_family == 'Debian'
  - ansible_facts.distribution_major_version | int >= 12

Both must be true. There is no list form for OR — write or in the expression, or restructure the inventory, which lesson 7 argues is usually the real answer.

What 2.21 does with a non-boolean

Here is a play designed to hit the classic trap. s_false is the string "false", which in every version of Jinja is truthy because it is a non-empty string.

Read-only / Safethe truthiness of things that look false— Evaluates each value in a Jinja inline conditional to show how Python truthiness sees it. All of these are read-only debug tasks.

$ ansible-playbook truth.yml

TASK [Report how each value evaluates in a raw Jinja conditional] **************
ok: [localhost] => {
  "msg": "s_false=TRUE s_no=TRUE s_zero=TRUE s_empty=FALSE b_false=FALSE n_zero=FALSE"
}

The string "false" is truthy. The string "no" is truthy. The string "0" is truthy. Only the empty string, the real boolean false and the integer 0 are falsy.

Now the same value used as a conditional:

Read-only / Safe2.21 refuses rather than guessing— A when: whose value is the string false. Rather than treating it as true, ansible-core 2.21 fails the task and names the origin of the offending value.

$ ansible-playbook truth.yml

TASK [This task runs even though s_false looks false] ***************************
[ERROR]: Task failed: A 'when' expression failed: Conditional result (True)
was derived from value of type 'str' at 'truth.yml:5:14'. Conditionals must
have a boolean result.

Origin: truth.yml:25:13

23       ansible.builtin.debug:
24         msg: "I ran. when was the string false."
25       when: s_false
             ^ column 13

Broken conditionals can be temporarily allowed with the
'ALLOW_BROKEN_CONDITIONALS' configuration option.

fatal: [localhost]: FAILED!

Read the error carefully, because it is unusually good. It reports:

the result it derived (True),
the type it came from (str),
the origin of the value — truth.yml:5:14, where s_false was defined,
the origin of the conditional — line 25, where it was used.

Two file positions, one for the definition and one for the use. That is exactly the pair you need to fix this class of bug and exactly the pair older versions did not give you.

The escape hatch, and its expiry

Read-only / Safethe setting, its default and its removal date— Reads the full definition of the setting. Note the default is false and the behaviour it restores is itself deprecated.

$ ansible-config list | grep -A 17 '^ALLOW_BROKEN_CONDITIONALS'

ALLOW_BROKEN_CONDITIONALS:
default: false
description:
- When enabled, this option allows conditionals with non-boolean results to be used.
- A deprecation warning will be emitted in these cases.
- By default, non-boolean conditionals result in an error.
- Such results often indicate unintentional use of templates where they are not
  supported, resulting in a conditional that is always true.
- When this option is enabled, conditional expressions which are a literal 'None'
  or empty string will evaluate as true for backwards compatibility.
env:
- name: ANSIBLE_ALLOW_BROKEN_CONDITIONALS
ini:
- key: allow_broken_conditionals
  section: defaults
type: boolean
version_added: '2.19'

Turning it on downgrades the error to a deprecation warning that names the removal version:

Read-only / Safethe same play with the escape hatch on— The task now runs, with a deprecation warning naming ansible-core 2.23 as the version where the option goes away.

$ ANSIBLE_ALLOW_BROKEN_CONDITIONALS=True ansible-playbook truth.yml

TASK [This task runs even though s_false looks false] ***************************
[DEPRECATION WARNING]: Conditional result (True) was derived from value of
type 'str' at 'truth.yml:5:14'. Conditionals must have a boolean result.
This feature will be removed from ansible-core version 2.23.

Broken conditionals are currently allowed because the
'ALLOW_BROKEN_CONDITIONALS' configuration option is enabled.

ok: [localhost] => {
  "msg": "I ran. when was the string false."
}

TASK [With the bool filter is skipped] *****************************************
skipping: [localhost]

Treat this as a migration tool with a deadline, not a setting. Turn it on to get an upgrade over the line, collect the deprecation warnings into a list of files to fix, fix them, turn it off. It stops working in 2.23.

The traps that are still traps

The 2.21 change catches conditionals that evaluate to the wrong type. It does not catch conditionals that evaluate to a boolean by a wrong route.

String comparison where you meant numeric

Read-only / Safea comparison that is a valid boolean and a wrong answer— Comparing version strings lexically. The result is a proper boolean, so nothing errors, and it is wrong.

$ ansible-playbook truth.yml

TASK [String comparison against an integer-looking fact] ***********************
ok: [localhost] => {
  "msg": "compare: False but int-compared: True"
}

'26' > '9' is false, because string comparison is character by character and '2' sorts before '9'. '26' | int > '9' | int is true.

This matters because ansible_facts.distribution_major_version is a string. A conditional written as:

when: ansible_facts.distribution_major_version > '9'

is a perfectly valid boolean expression that returns false on Debian 12, RHEL 10 and Ubuntu 26 — every host you actually wanted it to match. Nothing errors. The task skips. The recap is green.

Always cast:

when: ansible_facts.distribution_major_version | int >= 12

`is defined` on something that is defined and empty

Covered in Part XIV lesson 3 and it belongs here too, because it is a conditional problem: ansible_facts.default_ipv4 is {} on a host with no default route. is defined is true. The next line fails.

Test the value you are about to read.

`| bool` on a string that is not a boolean word

| bool maps a specific set of words. 'true', 'yes', 'on', '1' become true; 'false', 'no', 'off', '0' become false. Anything else — 'enabled', 'TRUE ' with a trailing space, 'y' — is not guaranteed and does not error in a way you will notice.

If a value’s source is a text file, INI fact, or environment variable, normalise at the boundary rather than at each use:

- name: Normalise once, near the source
  ansible.builtin.set_fact:
    app_maintenance_mode: >-
      {{ (ansible_facts.ansible_local.app.maintenance | default('false'))
         | trim | lower | bool }}

A `when` that matches zero hosts is a green run

This is the failure mode to internalise from this part.

A conditional comparing against a mis-cased or misspelled value — 'ubuntu' instead of 'Ubuntu', 'RedHat' instead of 'RedHat' with the wrong capitalisation — matches nothing. Every task skips. The recap reports ok, changed=0, failed=0, unreachable=0.

That is byte-for-byte what a correct, idempotent, already-converged run looks like. There is no signal distinguishing them.

Two habits that catch it:

Compare the changed count to the previous run. A play that normally changes something and suddenly changes nothing on its first run after an edit is the signal.
Log the skip. Where a conditional is load-bearing, add a debug on the negation that says which hosts were excluded and why. A skip nobody can see is indistinguishable from a bug.

Assembling a conditional that holds up

Read-only / Safethe same requirement, written defensively— Casts the version, uses a namespaced fact, tests the exact value being read, and prints the excluded hosts.

- name: Apply the modern configuration on supported releases
ansible.builtin.template:
  src: app.conf.j2
  dest: /etc/app/app.conf
  mode: '0644'
when:
  - ansible_facts.os_family == 'Debian'
  - ansible_facts.distribution_major_version | int >= 12

- name: Record hosts excluded by the release check
ansible.builtin.debug:
  msg: >-
    SKIPPED {{ inventory_hostname }}:
    {{ ansible_facts.distribution }}
    {{ ansible_facts.distribution_major_version }} is below the
    minimum supported release
when:
  - ansible_facts.os_family == 'Debian'
  - ansible_facts.distribution_major_version | int < 12

The second task is not decoration. On a fleet where five hosts are on an old release, that debug is the only thing that will tell you so — and it is the difference between “the run was green” and “the run was green and here are the five hosts it deliberately did not touch”.

Under the hood

when is evaluated per host, per task, immediately before the task would run. That is why a conditional can read a fact gathered earlier in the same play, and why it can read a variable a previous task set with set_fact.

The 2.21 change lives in that evaluation step. The expression is evaluated, and then the result is checked: if it is not a boolean, Ansible reports where the non-boolean value originated rather than applying Python truthiness to it. That origin tracking is why the error can name the line where the variable was defined, several files away from the conditional — the value carries its provenance with it.

The same origin machinery is what produces the pointer-and-caret excerpts in the error output. It is a substantial improvement in diagnosability across the whole of 2.19 onwards, and conditionals are where you notice it first because conditionals are where type confusion concentrates.

One consequence worth knowing: when on a block is inherited by every task inside it, and is evaluated independently for each of those tasks rather than once for the block. A block-level when reading a variable that a task inside the block modifies will therefore see the modified value for the tasks that follow.

What happens if a conditional references a variable that does not exist?

The task fails on that host with an undefined-variable error, and the host is dropped from the rest of the play.

That is the right default and it is worth resisting the reflex to suppress it. The two suppressions people reach for have very different qualities:

# Reasonable: an explicit default, at the point of use.
when: app_feature_enabled | default(false)

# Usually wrong: treats "the variable is missing" as "do not run",
# which hides a typo in the variable name indefinitely.
when: app_feature_enabled is defined and app_feature_enabled

The second form means a misspelt variable name silently disables the task forever, on every host, with a green recap. The first at least puts the intended fallback in the file where a reviewer can disagree with it.

Better than either: define the variable for every host in group_vars/all with its default value, and let the layering rule do the work. Then the conditional is a plain boolean test, an undefined error means a genuine inventory gap, and there is no default() to get out of step with the real default.

Knowledge check

Why this matters

Every other failure in Ansible eventually shows you red text. A wrong conditional shows you a clean run.

That asymmetry is why this lesson spends as much time on the failures that still pass as on the ones 2.21 now catches. The version upgrade removed an entire category — conditionals that were true because a string was non-empty — and that is genuinely worth having. What remains is the harder category: expressions that are well-typed, well-formed, reviewed, and compare the wrong two things.

For those, the defence is not syntax. It is knowing what a green run does not prove, checking the changed count against what you expected, and making load-bearing skips visible in the output so that “we deliberately excluded five hosts” and “we accidentally excluded all of them” stop looking the same.

when is raw Jinja