Reading Jinja and templating errors · Ansible

Templating errors used to be the worst diagnostic experience in Ansible. A Python traceback would surface, name a file that was not the file with the mistake in it, and leave you grepping for braces.

On ansible-core 2.21 that changed, and the change is worth learning deliberately because the new output answers a question the old one did not: where did the offending value come from?

The caused-by chain

Every templating failure on 2.21.3 is reported as a chain of frames, outermost first, each with an Origin: and a source excerpt.

Read-only / Safean undefined variable, in full — executed on ansible-core 2.21.3— A single debug task referencing a variable nobody defined. Local connection, nothing modified. The output is shown complete because its structure is the lesson.

$ ansible-playbook -i inv.ini j1.yml

[ERROR]: Task failed: Finalization of task args for 'ansible.builtin.debug'
failed: Error while resolving value for 'msg': 'app_port' is undefined

Origin: /home/ops/estate/j1.yml:4:7

2   gather_facts: false
3   tasks:
4     - name: Undefined variable
      ^ column 7

<<< caused by >>>

Finalization of task args for 'ansible.builtin.debug' failed.
Origin: /home/ops/estate/j1.yml:5:7

3   tasks:
4     - name: Undefined variable
5       ansible.builtin.debug:
      ^ column 7

<<< caused by >>>

Error while resolving value for 'msg': 'app_port' is undefined
Origin: /home/ops/estate/j1.yml:6:14

4     - name: Undefined variable
5       ansible.builtin.debug:
6         msg: 'listening on {{ app_port }}'

Read it bottom-up. The last frame is the innermost cause and the one with the precise location: file, line 6, column 14, with the source line printed. The frames above it are the layers that failed as a consequence: the argument could not be finalised, so the task failed.

The five shapes

Undefined variable

Error while resolving value for 'msg': 'app_port' is undefined

The name is exactly the name that failed to resolve — including, in a chain like item.shell, the part that was missing. It means the variable does not exist at this point in this play for this host, which is not the same as “does not exist in the repository”. The previous lesson is the procedure.

The fix is either to define it or to supply a default, and choosing between those is a design decision: a default hides a missing value, and for something like a port or a hostname you usually want the failure.

Syntax error in the template

Syntax error in template: unexpected 'end of print statement'

Read-only / Safea malformed expression, innermost frame only — executed on 2.21.3— The last frame of the chain for msg: {{ 1 + }}. Column 14 is the opening of the expression.

$ ansible-playbook -i inv.ini j5.yml

Error while resolving value for 'msg': Syntax error in template: unexpected
'end of print statement'
Origin: /home/ops/estate/j5.yml:16:14

14     - name: unexpected token
15       ansible.builtin.debug:
16         msg: "{{ 1 + }}"
              ^ column 14

The message names what the parser expected next. unexpected 'end of print statement' means the expression ended early — a missing operand, an unclosed bracket, a filter with no argument. unexpected '}' usually means a nested {{ }} inside an expression that was already an expression.

Filter applied to the wrong type

The filter plugin 'ansible.builtin.join' failed: 'int' object is not iterable

Read-only / Safea filter chain where one step changed the type — executed on 2.21.3— app_name is a string; length makes it an int; join then has nothing to iterate. Innermost frame shown.

$ ansible-playbook -i inv.ini j2.yml

Error while resolving value for 'msg': The filter plugin 'ansible.builtin.join'
failed: 'int' object is not iterable
Origin: /home/ops/estate/j2.yml:8:14

6     - name: Filter applied to the wrong type
7       ansible.builtin.debug:
8         msg: '{{ app_name | length | join(",") }}'

The named filter is the one that failed, not necessarily the one that is wrong. Here join failed because length before it produced an integer. In a long filter chain, work leftwards from the named filter and print the intermediate values with debug and var: until the type changes to something you did not expect.

A conditional that is not a boolean

This is the shape that changed most on 2.21, and it deserves its own section.

Read-only / Safewhen: enable_tls where enable_tls is the string 'false' — executed on 2.21.3— The variable is defined as a quoted string. On 2.21.3 the conditional refuses to evaluate it, and the innermost frame points at the definition rather than at the when clause.

$ ansible-playbook -i inv.ini j3.yml

A 'when' expression failed.
Origin: /home/ops/estate/j3.yml:9:13

7       ansible.builtin.debug:
8         msg: 'TLS branch taken'
9       when: enable_tls
            ^ column 13

<<< caused by >>>

Conditional result (True) was derived from value of type 'str' at
'/home/ops/estate/j3.yml:4:17'. Conditionals must have a boolean result.
Origin: /home/ops/estate/j3.yml:9:13

The string 'false' is now a hard error, and that is the good outcome

enable_tls: 'false' is a three-character string. In Python and in Jinja, any non-empty string is truthy, so when: enable_tls has historically evaluated to true for the value 'false' — silently, with no warning, taking the branch the author was trying to avoid.

On ansible-core 2.21.3 the task fails instead, with a message that names the derived result (True), the offending type (str), and the file, line and column where the value was defined — j3.yml:4:17, which is the vars entry, not the when clause.

That last part is the genuinely new capability. The error points at the definition site across the whole variable resolution chain, so a value set in a group_vars file three directories away is named directly.

Where does the string come from? Almost always from a place that has no YAML typing: an --extra-vars value on the command line, a variable from an environment lookup, a value read from a JSON or INI source, or a quoted literal someone added to silence a linter. Fix the source. If you cannot, convert explicitly with the bool filter and be aware that it is a conversion, not a repair.

Templating delimiters in `when`

when takes a bare Jinja expression. Writing when: "{{ enable_tls }}" wraps it in an extra evaluation.

Verified on 2.21.3: with enable_tls set to the string 'false', the braces form produced skipping with no error and no warning, where the bare form failed loudly. The two forms are not equivalent, and the braces form is the one that can quietly do the wrong thing.

Write conditionals bare:

Read-only / Safeconditionals, correct and incorrect— Structure only; nothing is executed. The first form is correct, the second is the one to remove during review.

# correct — when takes a bare expression
- name: Configure TLS
ansible.builtin.template:
  src: tls.conf.j2
  dest: /etc/app/tls.conf
  mode: '0640'
when: enable_tls | bool

# incorrect — the extra evaluation changes the semantics
- name: Configure TLS
ansible.builtin.template:
  src: tls.conf.j2
  dest: /etc/app/tls.conf
  mode: '0640'
when: "{{ enable_tls }}"

`default()` versus `default(omit)`

default(value) substitutes a value. default(omit) substitutes a special marker that tells Ansible to remove the argument entirely, so the module applies its own default.

Read-only / Safeomit, used where it is meaningful— Where shell is absent from an item, the shell argument is not passed to the module at all, so the system default applies. Structure only; the user module is shown for illustration and is not executed here.

- name: Create accounts, letting the system choose the shell where unspecified
ansible.builtin.user:
  name: '{{ item.name }}'
  shell: '{{ item.shell | default(omit) }}'
  state: present
loop: '{{ users }}'

Under the hood

Why can 2.21 name the line where a value was defined, when previous releases could only name where it was used?

Because templated values now carry origin metadata through resolution. When the YAML is parsed, each scalar is tagged with the file, line and column it came from, and that tag survives being stored in a variable dictionary, merged with other sources, and later evaluated in a conditional. The conditional failure message can therefore report both the expression that failed and the provenance of the value it was given.

This is why the when error above names two locations that are in different parts of the file: line 9 is the conditional, line 4 column 17 is the vars entry that set the string. On a real estate the second location is frequently a group_vars file in a different directory, which is exactly the case that used to be hardest.

It is worth noting what this does not give you: full provenance for every variable, on demand. The tag is reported when an error occurs because the error handler has the value in hand. There is still no command that prints where a working variable came from, for the reasons covered in the previous lesson.

What happens if the error points at a line inside a role I did not write?

That is usually correct rather than misleading, and the chain tells you how you got there.

Read every frame, not just the last one. The outer frames name the task and the file that invoked the role, so the chain reads: your play called this role, the role called this task, this task evaluated this expression, which failed on this value. The role is where the expression lives; your play is often where the wrong value came from.

The practical split: if the innermost frame is an undefined variable whose name is part of the role’s documented interface, the bug is in your invocation — you did not supply a required variable, and the role should have declared it in an argument spec. If the innermost frame is a type or syntax error inside the role’s own logic, the bug is in the role, and the version you pinned is the relevant fact for the issue report.

Knowledge check

Why this matters

Templating errors are where beginners lose hours and experienced people lose minutes, and the difference is entirely in how the message is read.

The 2.21 error format is a substantial improvement, and it rewards being learned rather than skimmed. It tells you the innermost expression, the value that broke it, the type that value had, and — for conditionals — the line in whichever file across your whole variable hierarchy defined it. That last capability replaces the single most tedious task in Ansible debugging: working out which of forty possible files set a variable to a string when you expected a boolean.

The corollary is that a play which produces no errors is not thereby correct. The braces-in-when form skips silently, default(omit) inside a string renders as nothing, and a string 'false' used anywhere other than a conditional is still truthy. The errors you can read are the easy half; the quiet cases are why the review checklist exists.