Home Assistant Guide

Jinja2 Templates: Common Quirks & Troubleshooting Tips

Templates let you do clever things in Home Assistant - like combine sensor values, make decisions, or format messages. Home Assistant uses a system called Jinja2 for templates. While powerful, it has some quirks that can trip up beginners. Here's a guide to the most common issues, odd behaviors, and simple fixes!

1. Everything is a String!

• Even if a sensor shows a number (like 21.5), in templates it's actually a string. If you try to do math without converting, things won't work as expected.
• Wrong:

  {{ states('sensor.temp1') + states('sensor.temp2') }}

  (This joins them as text: "2118" instead of 39)
• Right:

  {{ states('sensor.temp1') | float + states('sensor.temp2') | float }}

2. Unknown, Unavailable, and None Values

• If a sensor or entity is missing, or hasn't reported yet, its value might be "unknown", "unavailable", or None. If you try to do math or compare with these, you'll get errors!
• Safe default:

  {{ states('sensor.humidity') | float(0) }}

  (This will use 0 if the value isn't a number)

3. State vs. Attribute: Don't Mix Them Up

• The state is the main value.
  Example:

  {{ states('sensor.door') }}

• Attributes are extra info.
  Example:

  {{ state_attr('sensor.door', 'battery') }}

• Never use dot notation for attributes (like sensor.door.battery) in Home Assistant templates - always use state_attr().

4. My Template Doesn't Update When I Expect

• Templates in automations only update when one of the entities inside changes. They do NOT update constantly or on every line.
• If you want to "force" an update, reference something that updates regularly, like now(), but be careful - it can make your automation run often!
• Example:
  

  {{ now().hour }}

5. Errors with Quotes and Special Characters

• Mixing single (') and double (") quotes is a common cause of errors. Try to keep them straight, or "flip" them as needed:

  {{ "He said: 'Hello!'" }}

  or

  {{ 'Use "quotes" inside single quotes.' }}

6. Template Works in Dev Tools, Not in Automation

• Some variables or entities are available in Developer Tools > Templates, but not inside an automation. Double-check your context!

7. TemplateError: UndefinedError

• This means you referenced something that doesn't exist (typo in the entity name, or it's not loaded).
• Check for typos, or use | default('fallback value') to avoid errors:

  {{ states('sensor.made_up') | default('not found') }}

8. Line Breaks and Formatting

• Jinja2 squashes extra spaces and line breaks by default. If you want a template to output multi-line text (like in a notification), use \n for line breaks, or wrap your message in triple quotes.
• Example:
  

   {{ "Line 1\nLine 2" }} 

Quick Tips for Avoiding Template Headaches

• Test your template in Developer Tools > Templates first!
• Use | float(0) or | int(0) to make sure you're working with numbers.
• Handle unknown and unavailable states in all your templates.
• Use state_attr() for attributes, never dot notation.
• Check for typos in entity and attribute names.