Runbook: Troubleshoot a Jinja error

Templating failures look intimidating and are usually the fastest class of Ansible fault to fix, because the error names both the key that failed and the reason. The work is reading it precisely and then reproducing it somewhere that costs nothing.

The messages in this runbook were produced by running the failures against ansible-core 2.21.3. They changed shape in recent releases - older material describes a different wording - so match against these rather than against memory.

When to use this runbook

• A task fails with a templating or rendering error.
• A when: expression fails rather than evaluating true or false.
• A template renders but produces content the consuming program rejects.
• A play works on most hosts and fails on one.

Blast radius

None. Everything here can be reproduced locally against a fake inventory. No managed host is required to diagnose a templating fault, and that is the main practical point of this runbook.

Step 1: Classify the message

Verified against 2.21.3:

Undefined variable

fatal: [web01.example.com]: FAILED! => {"msg": "Task failed: Finalization of
task args for 'ansible.builtin.debug' failed: Error while resolving value for
'msg': 'app_listen_port' is undefined"}

Exit code 2. Read three things: the module, the key (msg), and the name (app_listen_port). The variable does not exist in scope at that point.

Attribute that does not exist

"Error while resolving value for 'msg': object of type 'dict' has no
attribute 'listen_port'"

The variable exists. The structure is not what the expression assumed - cfg.listen_port where cfg is a dict without that key.

Type error

"Task failed: A 'when' expression failed: Error rendering expression:
'>' not supported between instances of 'str' and 'int'"

Both values exist. One is a string where a number was expected, almost always because it was quoted in YAML.

Template syntax error

"Error while resolving value for 'msg': Syntax error in template:
unexpected end of template, expected 'end of print statement'."

The expression itself is malformed - an unclosed {{, a stray quote, a filter without arguments.

Step 2: Locate the expression

The message names the task and the key. Together they locate the expression.

# By the task name from the failure
grep -rn 'Render the site configuration' --include='*.yml' roles/ site.yml

# By the variable name, in tasks and in templates
grep -rn 'app_listen_port' --include='*.yml' --include='*.j2' . --exclude-dir=.git

For a template module failure the expression is in the .j2 file, not in the playbook. The message names the module and the destination but not the line, so grep the template.

Step 3: Reproduce in isolation

This is the step that turns a slow investigation into a fast one. Build a two-line inventory that connects to nothing, and iterate on the expression at full speed.

# repro-inv.yml
all:
vars:
  ansible_connection: local
  ansible_python_interpreter: "{{ ansible_playbook_python }}"
hosts:
  testhost:

- name: Reproduce the templating failure
hosts: testhost
gather_facts: false
vars:
  cfg:
    listen: 8080
  servers:
    - name: a
    - name: b
tasks:
  - name: The expression that failed
    ansible.builtin.debug:
      msg: "{{ cfg.listen_port }}"
    ignore_errors: true

  - name: What is actually in there?
    ansible.builtin.debug:
      msg: "keys={{ cfg.keys() | list }} type={{ cfg | type_debug }}"

ansible-playbook -i repro-inv.yml repro.yml

Sub-second, no network, no managed host, no risk. Paste the real data structure in and iterate on the expression until it renders.

Step 4: Undefined - absent everywhere, or absent here?

# Does any host have it?
ansible all -m debug -a 'var=app_listen_port' -o | head -20

# Where is it set?
grep -rn --include='*.yml' -E '^\s*app_listen_port\s*:' . --exclude-dir=.git

Step 5: Attribute - inspect the real structure

Do not read the expression again. Print the data.

- name: Show the structure, not the assumption
ansible.builtin.debug:
  msg: |
    type:  {{ cfg | type_debug }}
    keys:  {{ cfg.keys() | list if cfg is mapping else 'not a mapping' }}
    value: {{ cfg | to_nice_json }}

ansible web01.example.com -m setup -a 'filter=ansible_default_ipv4' -o
ansible web01.example.com -m setup -a 'filter=ansible_mounts' -o | head -30

Facts are the usual source of this failure. ansible_default_ipv4 is a dict on a host with a default route and an empty dict on a host without one, so ansible_default_ipv4.address fails on exactly the hosts with unusual networking - which is why it works on nineteen hosts and fails on the twentieth.

- name: Address, with an honest fallback
ansible.builtin.debug:
  msg: >-
    {{ ansible_facts['default_ipv4']['address']
       | default(ansible_facts['all_ipv4_addresses'] | first) }}

Step 6: Type - check it, do not assume it

- name: What types are these really?
ansible.builtin.debug:
  msg: >-
    app_port={{ app_port }} ({{ app_port | type_debug }})
    threshold={{ threshold }} ({{ threshold | type_debug }})

Verified on 2.21.3: 8080 | type_debug is int, '8080' | type_debug is str, and comparing them raises the type error shown in Step 1.

YAML decides the type, and quoting is not cosmetic:

Verified on 2.21.3 by rendering each through type_debug:

port: 8080        -> int 8080
port: "8080"      -> str "8080"
enabled: yes      -> bool True
enabled: "yes"    -> str "yes"
version: 1.10     -> float 1.1        (the trailing zero is gone)
version: "1.10"   -> str "1.10"
mode: 0644        -> int 420          (parsed as YAML 1.1 octal, = 0o644)
mode: '0644'      -> str "0644"

The version row costs real time: a version number written as a bare 1.10 becomes the float 1.1, and every comparison and every rendered config line afterwards carries the wrong value with no error anywhere.

File modes are the subtler one. 0644 is parsed as octal by the YAML 1.1 rules PyYAML implements, giving the integer 420 - which is 0o644, so it happens to be right. But 644 without the leading zero is decimal 644, which is 0o1204: the sticky bit set and permissions that are not what anyone intended. The task reports success either way.

Quote file modes. mode: '0644' is unambiguous under every parser, and it is the one form that does not depend on knowing which of those two rows you wrote.

Convert explicitly at the point of comparison rather than hoping:

- name: Compare like with like
ansible.builtin.debug:
  msg: "over threshold"
when: (app_port | int) > (threshold | int)

Step 7: Syntax - check the YAML layer first

Jinja syntax errors are frequently YAML quoting errors wearing a disguise.

# Fails: YAML sees a flow mapping, not a Jinja expression
msg: {{ app_port }}

# Correct: quote the whole scalar when it starts with {{
msg: "{{ app_port }}"

# Fails: the inner double quotes end the outer scalar
msg: "{{ lookup("env", "HOME") }}"

# Correct: single quotes inside, double outside
msg: "{{ lookup('env', 'HOME') }}"

# Fails: unterminated expression
msg: "{{ app_port "

# Multi-line expressions: use a folded scalar
msg: >-
  {{ servers | map(attribute='name') | join(',') }}

A value that begins with {{ must be quoted. That single rule accounts for most of the syntax errors in this class.

Step 8: Rendering is not correctness

ansible-playbook -i inventories/production site.yml \
--limit web01.example.com --tags config --check --diff

- name: Render the site configuration, validated before activation
ansible.builtin.template:
  src: site.conf.j2
  dest: /etc/nginx/conf.d/site.conf
  owner: root
  group: root
  mode: '0644'
  backup: true
  validate: 'nginx -t -c %s'
notify: Reload nginx

validate: runs the checker against the rendered file before it replaces the live one. A template bug then fails the task with the program’s own error message, and the running configuration is untouched. It does not run in check mode - there is no rendered file to validate - so it is a real-run protection, not a dry-run one.

Verification

# The failing host now succeeds
ansible-playbook -i inventories/production site.yml \
--limit web01.example.com --check --diff

# A previously-working host is unchanged
ansible-playbook -i inventories/production site.yml \
--limit web02.example.com --check --diff

# Every host in the group renders
ansible-playbook -i inventories/production site.yml \
--limit web --check | tail -10

The middle check matters. A fix that adds a variable or changes an expression changes rendering for every host that uses the template, and the one you were debugging is not the one at risk.

Common patterns

Escalation

Escalate when:

• A fact or external data source changed shape. The template may be correct and the source may have moved.
• The failing expression is in a shared role or collection.
• A wrong rendered config was already activated on a service.
• Adding default() would let production render with a placeholder.