Django: The perils of string_if_invalid in templates

1. The default filter

Template:

{{ is_tall|default:True }}

Result without string_if_invalid:

True

Result with string_if_invalid = 'MISSING VARIABLE %s':

MISSING VARIABLE is_tall

The default filter is often used to select default values for missing variables. Enabling string_if_invalid breaks this pattern because the template engine then skips filters.

2. The yesno filter

Template:

{{ is_grande|yesno:'grande,tall' }}

Result without string_if_invalid:

tall

Result with string_if_invalid = 'MISSING VARIABLE %s':

MISSING VARIABLE is_grande

The yesno filter shows one of two strings based on a variable’s boolean value. In normal conditions, you can rely on missing variables evaluating as False and being replaced with the second string. But with string_if_invalid enabled, the filter is skipped, as per example #1.

3. {% filter %} around missing variables

Template:

{% filter lower %}{{ x }}{% endfilter %}

Result without string_if_invalid:

(empty)

Result with string_if_invalid = 'MISSING VARIABLE %s':

missing variable x

The filter tag applies a filter to a block’s contents. When wrapping content that includes string_if_invalid, it will also be filtered. This could prevent you from finding missing variables in the output, such as if using a case-sensitive search in the above example.

4. {% url %} encoding with default

Template:

{% url 'page' name|default:'home' %}

Result without string_if_invalid:

/home/

Result with string_if_invalid = 'MISSING VARIABLE %s':

/MISSING%20VARIABLE%20name/

The url tag constructs a URL, potentially with parameters. If one of those parameters is a missing variable, it will be replaced with string_if_invalid which is then URL-encoded. Again, this could prevent you from finding missing variables in the output with an automatic search. This one is particularly tricky since most {% url %} usage is within the href attribute, so it won’t be visibly rendered, but links will be broken.

5. {% url %} that would raise an exception

Template:

{% url 'page' name %}

Error without string_if_invalid:

NoReverseMatch("Reverse for 'page' with arguments '('',)' not found. 1 pattern(s) tried: ['(?P<name>[^/]+)/\\\\Z']")

Result with string_if_invalid = 'MISSING VARIABLE %s':

/MISSING%20VARIABLE%20name/

Since missing variables normally resolve to '', this fails to match the URL pattern, which requires at least one character. Enabling string_if_invalid makes the variable resolve to a non-empty string, allowing the URL to be resolved to a nonsense value, as above. “Muting” an exception like this is pretty undesirable for a “debugging tool“.

6. {% static %} encoding

Template:

{% load static %}{% static x %}

Result without string_if_invalid:

(empty)

Result with string_if_invalid = 'MISSING VARIABLE %s':

MISSING%20VARIABLE%20x

Like the first {% url %} example above, the static tag ends up URL-encoding the result from string_if_invalid. If you were searching for your string_if_invalid value in the output, you wouldn’t find it.

7. Functions marked with alters_data=True un-named

Template:

{{ data_alterer }}

Setup code:

def data_alterer():
    pass


data_alterer.alters_data = True

Context:

{"data_alterer": data_alterer}

Result without string_if_invalid:

(empty)

Result with string_if_invalid = 'MISSING VARIABLE %s':

MISSING VARIABLE %s

By default, if a variable lookup resolves to a function, Django’s template engine calls it. Functions can be marked with alters_data = True to prevent this behaviour, as documented under Variables and lookups. In such cases, the template engine falls back to string_if_invalid, but does not template it with the name of the missing variable. This could make it hard to determine the issue.

8. Function missing arguments un-named

Template:

{{ data_alterer }}

Setup code:

def needs_arg(x):
    pass

Context:

{"needs_arg": needs_arg}

Result without string_if_invalid:

(empty)

Result with string_if_invalid = 'MISSING VARIABLE %s':

MISSING VARIABLE %s

Following the above, a lookup function call fails due to missing arguments, the template engine will again fall back to string_if_invalid without templating the variable name.

9. Silent exceptions don’t name the variable

Template:

{{ raise_silent }}

Setup code:

class Silent(Exception):
    silent_variable_failure = True


def raise_silent():
    raise Silent()

Context:

{"raise_silent": raise_silent}

Result without string_if_invalid:

(empty)

Result with string_if_invalid = 'MISSING VARIABLE %s':

MISSING VARIABLE %s

If resolving a variable raises an exception that has silent_variable_failure = True set, the template engine will also fall back to string_if_invalid. But again, this pathway misses the variable name, making it less useful for debugging.

10. Custom tags receive the string_if_invalid value

Template:

{% yes_or_no x %}

Setup code:

@register.simple_tag
def yes_or_no(x):
    if x:
        return "Yes"
    else:
        return "No"

Result without string_if_invalid:

No

Result with string_if_invalid = 'MISSING VARIABLE %s':

Yes

Template tags, including custom ones, receive the resolved variable values and then act on them. If string_if_invalid is set, this changes the value received by the tag and can thus change its behaviour, in perhaps rather unexpected ways.