Why do I get numeric operator errors in Jinja? – Help Center

Numeric operator errors in Jinja usually mean that a math expression received a value that is not actually numeric.

In Jinja, the operators +, -, *, /, and % are meant for numbers. If a string, empty value, date string, or another non-numeric value reaches that expression, the template can fail during rendering.

What does this error mean

A numeric operator-related error happens when Jinja evaluates an expression that expects a numeric value, but receives a different type instead.

Common examples include:

Numeric operator + is allowed on numbers only
Not supported between instances of str and int
Not supported between instances of NoneType and int

This usually means that at least one operand in your expression is:

a string such as "3"
an empty or missing value
a date stored as text
a list or another non-numeric object

For more information, see Jinja errors, Jinja filters, and Jinja conditionals and tests.

Why this happens

The most common cause is a type mismatch between what your template expects and what your data actually contains.

For example:

A customer attribute looks numeric in the UI, but is stored as text.
A catalog field is empty for some customers or products.
A date is stored as a string and is used in time math before conversion.
A value is none and is still used in a comparison.
You use + on a list, expecting it to behave like an append operation.

How to fix it

Before using a value in arithmetic or numeric comparison, validate it or convert it first.

1. Validate the value first

Use Jinja tests to check whether a value exists, is not null, and is numeric before using it in numeric logic.

{% if item.price is defined and item.price is not none and item.price is number %}
  {{ item.price + 10 }}
{% endif %}

Useful checks include:

is defined
is not none
is number

These help prevent errors caused by missing or null values.

2. Convert strings to numbers

If the value is stored as text, convert it to a numeric value before using numeric operators.

{{ customer.loyalty_points | int + 10 }}

{{ item.price | float * 1.2 }}

Jinja supports both int and float filters. If conversion fails, they return 0 or 0.0 unless you provide a different default. See Jinja filters.

3. Convert date strings before doing math

If a date is stored as a string, convert it to a Unix timestamp first.

{% set order_time = customer.last_order_date | to_timestamp %}
{{ order_time + 86400 }}

This is especially important when you need to add or subtract seconds or reuse a date value in time-based expressions.

4. Add a fallback for empty values

If a value may be missing or blank, provide a safe default before using it in numeric logic.

{{ customer.discount_value | default(0, true) | int + 5 }}

This helps when attributes are undefined, blank, or optional.

5. Do not use `+` to append to arrays

If your goal is to grow a list, use list operations rather than treating the list as a numeric value.

{% append product_item to products_to_display %}

Examples

Example 1: String used in comparison

This fails because "3" is a string:

{% if "3" > 0 %}
  Valid
{% endif %}

Use this instead:

{% if "3" | int > 0 %}
  Valid
{% endif %}

Example 2: Empty value in a comparison

This can fail if item.price is empty or null:

{% if item.price > 0 %}
  {{ item.price }}
{% endif %}

Safer version:

{% if item.price %}
  {% if item.price | float > 0 %}
    {{ item.price }}
  {% endif %}
{% endif %}

Example 3: Date string used in math

This is risky if the source value is still a string:

{{ customer.last_order_date + 86400 }}