Whitespace Control and Mistakes

Jinja2 keeps the whitespace around its tags, so a {% for %} loop that looks clean in the .j2 renders a config full of blank lines — one per iteration, where the {% %} line used to be. The output is correct but ugly, and on some parsers ugly tips over into broken. The fix is trim markers ({%- and -%}) and the trim_blocks / lstrip_blocks settings, which strip the newline and leading space a control tag leaves behind.

This is also the topic that collects the templating footguns that bite once a file stops being trivial: how undefined variables behave, and why a variable that happens to contain {{ }} gets re-rendered as if it were a template. None of these are exotic. They are the everyday ways a working template starts producing noisy diffs or silent wrong output, and each has a clean fix once you know it is there.

The Blank-Line Problem

A {% for host in groups['web'] %} line, the matching {% endfor %}, and any {% if %} each leave their own newline in the output. Loop over five hosts and the rendered upstream block carries a scatter of blank lines through it, because every control-tag line that printed nothing still left behind the newline that followed it in the source. It is harmless to nginx but it makes diffs noisy, and stricter readers — pg_hba.conf among them — are less forgiving.

Trim Markers

{%- strips whitespace before the tag, and -%} strips it after. Writing the loop control lines as {% for ... -%} and {%- endfor %} removes the newlines they would otherwise emit, giving tight output without restructuring the template. The dashes are surgical — you put them exactly where a stray newline is coming from, and leave the rest of the tag alone.

# without trimming — one blank line per iteration
{% for host in groups['web'] %}
server {{ hostvars[host]['ansible_host'] }}:8000;
{% endfor %}

# with trim markers — tight output, no blank lines
{% for host in groups['web'] -%}
server {{ hostvars[host]['ansible_host'] }}:8000;
{%- endfor %}

The danger is over-trimming. Put -%} on a line where you actually wanted the trailing newline and you collapse two directives onto one line, breaking the file just as thoroughly as the blank lines did. Trim markers cut both ways: under-trimming leaves noise, over-trimming fuses lines. The cure for both is to look at the rendered output, not the template, when deciding where a dash belongs.

trim_blocks and lstrip_blocks

Sprinkling a dash on every tag gets tedious, so Jinja2 offers two settings that do it wholesale. trim_blocks removes the first newline after a block tag, and lstrip_blocks strips the leading whitespace before one. Set in the role's configuration, they give you clean output without decorating every tag with a -. For config templates this is the pragmatic default — turn both on and most loops and conditionals render tight automatically.

The trade-off is that these settings change the bytes of existing templates too. Flip them on a template that quietly relied on the old whitespace and its output shifts, sometimes in ways that matter. That is not a reason to avoid them — it is a reason to flip them deliberately, with the rendered diff in front of you, rather than as an afterthought that silently rewrites a dozen config files at once.

Undefined-Variable Behavior

By default, an undefined variable raises an error at render time. That strictness is exactly what you want for config files: a typo in a variable name fails the play loudly instead of rendering a blank into app.env and letting the app boot with a missing setting. The default is your friend, and the instinct to loosen it — so a missing variable "just renders empty" — is a bug waiting to ship a half-blank config.

The right way to handle a genuinely optional value is not to rely on undefined-becomes-empty but to guard it explicitly with default. {{ optional_setting | default('off') }} says out loud what the missing-value behavior is, where depending on silent emptiness leaves it implicit and fragile. Strict by default, explicit defaults where you mean them — that combination keeps a missing variable from ever silently reaching a live file.

Recursive Templating

Ansible re-renders a variable whose value itself contains {{ }}. That is usually a feature: a group_vars value like base_url: "https://{{ domain }}" resolves correctly because Ansible templates the value before using it. The problem is when a value contains literal braces it did not mean as template syntax — a regex like {{2,4}}, a Prometheus query, a password that happens to contain {{. Ansible tries to evaluate it as a template and either fails or mangles the value.

The fix is to mark the value as not-to-be-templated. Wrap it in {% raw %}...{% endraw %} in a template, or tag it !unsafe in a vars file, and Ansible leaves the braces alone. This is the last footgun in the chapter and the most surprising, because the data looks fine until the one run where a password with the wrong character in it brings down a deploy with an error about an undefined template variable that you never wrote.