ReservedVariableName

Last edit: Jul 21, 2026

ReservedVariableName

Severity: error | Type: LiquidHtml

Liquid reserves the literals true, false, nil, null, empty, and blank. Assigning to one of these names is silently accepted, but reading the name always returns the built-in literal — never the value you assigned. Code that assigns to a reserved literal therefore never works and always indicates a bug.

This check reports reserved literals used as:

{% assign %} targets
{% capture %} targets
{% parse_json %} targets
{% function %} result variables
{% graphql %} result variables (both file-based and inline)
{% hash_assign %} targets
{% for %} and {% tablerow %} loop variables
{% increment %} and {% decrement %} counters
{% background %} job id variables
{% catch %} error variables (inside {% try %} blocks)

Reading the literals is of course still valid — comparisons like {% if items == empty %} or assignments of the literal value like {% assign flag = true %} are not reported. Names that merely contain a reserved word (e.g. empty_result) are also fine.

Examples

✗ Incorrect Code Example (Avoid using this):


{% assign empty = '{}' | parse_json %}
{% comment %}'empty' still resolves to the empty literal — the parsed hash is lost{% endcomment %}
{% function null = 'lib/queries/find', id: 1 %}
{% for blank in items %}{{ blank }}{% endfor %}

✓ Correct Code Example (Use this instead):


{% assign empty_hash = '{}' | parse_json %}
{% function result = 'lib/queries/find', id: 1 %}
{% for item in items %}{{ item }}{% endfor %}

{% comment %}Reading the literals is valid:{% endcomment %}
{% if items == empty or name == blank %}
  Nothing to show
{% endif %}
{% assign flag = true %}

Configuration

The default configuration for this check:

ReservedVariableName:
  enabled: true
  severity: error

Disabling This Check

This check should not be disabled. Assigning to a reserved Liquid literal never has the intended effect — reading the name always returns the literal — so every offense it reports is a real defect.

ReservedVariableName