Repository navigation
Checks and Strict
Two ways of dealing with a card that has been given something wrong. Checks are written in the template: its author says what counts as a problem with the values a card passes, and what the card should do about it. Strict is set on the card, or on the whole dashboard: it says how hard a card takes the problems its build runs into, from rendering anyway to refusing.
Both are new in v2.9.0, apart from strict: true, which has refused cards with unset
variables since v1.2.0 and still does exactly that.
On this page: Checks: checks: ·
Showing what failed: __alerts__ ·
A card of its own while something is wrong: alert: ·
Strict, one level at a time ·
For a whole dashboard, view or section: decluttering_strict: ·
How checks count to strict
A template that only works with a real sensor, or that needs a name to make sense, can say so itself rather than leaving each card to show Entity not found. Each check has a condition, a message, and how serious it is:
decluttering_templates:
room_temperature:
default:
- sensor: sensor.[[room]]_temperature
checks:
- name: No sensor
condition: '[[sensor|exists]]'
fail_on: false
level: error
message: There is no [[sensor]] in Home Assistant.
- name: No name
condition: '!name'
message: No name was given, so the sensor's own is shown.
- level: info
condition: true
message: Built for [[room]].
card:
type: tile
entity: '[[sensor]]'
name: '[[name?]]'- type: custom:decluttering-card-plus
template: room_temperature
variables:
- room: kitchen
- name: Kitchen
- type: custom:decluttering-card-plus
template: room_temperature
variables:
- room: bathroom # there is no sensor.bathroom_temperature
- name: BathroomThe kitchen card passes both checks and builds as normal, with Built for kitchen. in the browser console. The bathroom card fails the first: it still builds, and because the check is an error, the debug report opens under it with the failed check at the top.

| Key | What it does |
|---|---|
condition |
What is checked. See below |
fail_on |
Whether the check fails when the condition comes out true (the default) or false. fail_on: false turns a condition round: the check above fails when the sensor does not exist |
level |
info, warn (the default; warning works too) or error. See What each level does
|
message |
What to say. Placeholders are filled in with the card's values, so it can name what was wrong. Without one, the card says Check "No sensor" on template "room_temperature" failed. |
name |
A name for the check, shown beside its message in the report |
continue_rendering |
For an error: false stops the card being built at all. Anything else, or leaving it out, builds the card anyway |
checks: takes a list, or a single check written as a mapping. Checks run in the order they
are written, all of them, against the card's values before the card is built, so a
default:, a let: and anything decluttering_defaults
gives are all counted. A template's own preview in the template editor has no card's values,
so it runs none.
| Written | The condition is true when |
|---|---|
name |
the variable is a yes, read the way bool reads it |
!name |
the variable is a no, or not set |
name=text |
the variable is exactly that text |
name!=text |
the variable is anything but that text, unset included |
text with placeholders, '[[sensor|exists]]'
|
the text, once filled in, is a yes. Any placeholder left unfilled makes it a no |
true or false
|
always that |
These are the forms show_if
uses, so a leading if: or unless: is fine too. A condition the card cannot read at all,
such as room==kitchen, is skipped rather than failed, so a typo never stops a card, and a
level: it does not know is read as warn. The template editor's lint names both, and any
key in a check that is not one of the six above.
| Level | When the check fails |
|---|---|
info |
It is said in the browser console, and nowhere else. Useful for a note while you build a template |
warn |
It goes in the warnings the card keeps: in the console, in the card editor and at the top of the debug report. The card builds as normal |
error |
All of that, and the debug report shows under the card even with debug: off, so the problem is in front of whoever is looking. With continue_rendering: false the card is not built at all |
A card stopped by continue_rendering: false fails the way any card that cannot be built
does: its on_error: decides what
shows instead, on_error: hide included, and without one it shows A check stopped this
card being built: and the message. The template at the top of the page, with that one line
added to its error check:
decluttering_templates:
room_temperature_stop:
default:
- sensor: sensor.[[room]]_temperature
checks:
- name: No sensor
condition: '[[sensor|exists]]'
fail_on: false
level: error
message: There is no [[sensor]] in Home Assistant.
continue_rendering: false
card:
type: tile
entity: '[[sensor]]'
name: '[[name?]]'- type: custom:decluttering-card-plus
template: room_temperature_stop
variables:
- room: kitchen
- name: Kitchen
- type: custom:decluttering-card-plus
template: room_temperature_stop
variables:
- room: bathroom # there is no sensor.bathroom_temperature
- name: Bathroom
The kitchen card builds as before. The bathroom card is not built at all: where the tile saying Entity not found was, there is only the error card with the check's message, and no debug report, since there is no card for it to sit under.
Each failure is said in the console once per card, not on every rebuild, so a card that
follows a busy sensor with rebuild_on: does not repeat itself.
On a card with for_each or for_each_from, every copy is checked against its own values.
A copy that fails a check with continue_rendering: false stops the whole card, not just
itself.
A template with checks has every failed one in [[__alerts__]], so it can show them
itself. It is a mapping:
__alerts__:
all:
count: 2 # every failed check, info included
highest_level: error # the worst level among them, or empty when none failed
items:
- level: error
message: There is no sensor.bathroom_temperature in Home Assistant.
name: No sensor
template: room_temperature
- level: info
message: Built for bathroom.
template: room_temperature
info: { count: 1, items: [Built for bathroom.] }
warn: { count: 0, items: [] }
error: { count: 1, items: [There is no sensor.bathroom_temperature in Home Assistant.] }Read it with dotted names, and the list steps for the messages:
card:
type: markdown
content: >-
[[__alerts__.error.count]] errors, [[__alerts__.warn.count]] warnings:
[[__alerts__.warn.items|join:, ]]Each build works it out afresh, so it always says what this card's values failed, and a
value of the same name handed down from a card around it never wins. A template that reads
[[__alerts__]] without any checks: gets the empty version, with every count at 0.
A template can say what to show instead of its card while a check is failing, the way a card says what to show when it cannot be built:
decluttering_templates:
room_temperature_alert:
# default: and checks: as room_temperature above
alert:
type: markdown
content: |-
**The [[room]] card needs a look**
[[__alerts__.error.items|join:, ]] [[__alerts__.warn.items|join:, ]]
card:
type: tile
entity: '[[sensor]]'
name: '[[name?]]'type: custom:decluttering-card-plus
template: room_temperature_alert
variables:
- room: bathroom
alert: is written like card:, and for a badge, row or element template it is one of
those. It is built from the card's values, [[__alerts__]] included, whenever a warn or
error check has failed; a failed info check does not count. With an alert: to show,
an error no longer opens the debug report under the card, since the template has said what
to show.
Two things still win over it: a check with continue_rendering: false, which stops the card
being built at all, and strict: set to fail on errors.
On a repeat, each copy decides for itself, so one copy can show its alert while the others
build as normal.
Nothing normally stops a card rendering. A template can be edited after the cards that use
it, so a card that looks wrong now may be right in a moment, and placeholders left on the
card are easier to spot than a blank. strict: is for when you would rather know, or would
rather it refused. It takes the two kinds of problem a build can run into one at a time:
-
errors: a placeholder nothing gave a value, so it is still on the card as
[[name]]; -
warnings: a placeholder a step would not fill as asked, such as
[[tap|upper]]on a mapping or[[name|upper|raw]]withrawnot first, which the console explains; and every failedwarncheck.
type: custom:decluttering-card-plus
template: room_temperature
strict:
errors: fail
warnings: notice
variables:
- room: kitchen| Level | Setting | What the card does |
|---|---|---|
errors |
ignore |
Renders, brackets and all. The default |
report |
Renders, with the debug report under it | |
fail |
Refuses, with the error card, or its on_error:
|
|
warnings |
ignore |
Says them in the console only. The default |
notice |
Renders, with a small notice above it listing them, which can be closed | |
report |
Renders, with the debug report under it |
A report or a notice only appears when there is something in it. A notice that has been
closed stays closed until the warnings change. error: and warn: are read as errors:
and warnings:.

warnings: notice on the kitchen card from the top of the page, given no name.

errors: fail on the bathroom card: the error check refuses it.
strict: true is short for errors: fail with warnings left alone, which is what it has
always meant: a card with a variable left unset refuses, naming it, and nothing else
changes. strict: false is both levels at ignore. More on reading a refusal is in
Troubleshooting.
On the card, or in the template, beside card:, for every card that uses it. Each level is
taken from the nearest place that sets it, so a template can ask to fail on errors while
one card says errors: ignore for itself, and the card's word counts. A level a place
leaves out, or writes with a setting it does not have, is left to the next place.
Written where decluttering_defaults goes, decluttering_strict: sets strict for every
card under it:
decluttering_strict:
warnings: notice # every card on the dashboard
views:
- title: Testing
decluttering_strict:
errors: report # every card in this view
cards:
- type: custom:decluttering-card-plus
template: room_temperature
strict:
errors: fail # this card
variables:
- room: kitchenThe order, nearest first, is the card's strict:, the template's strict:, the section's
decluttering_strict:, the view's (or the view strategy's, for a
view written by a strategy), then the dashboard's.
Each level is settled on its own, so above the card fails on errors, from its own strict:,
and shows a notice for warnings, from the dashboard. A card with strict: false opts out of
everything above it.
It takes the same settings as strict:, true and false included.
A template's failed checks are problems like any other, so strict: counts them:
- A failed
warncheck is a warning. Underwarnings: noticeits message is in the notice, and underwarnings: reportit opens the report. - A failed
errorcheck fails the card undererrors: fail, as an unset variable does, with the error card saying A check stopped this card being built: and the check's message. That includesstrict: true. Analert:in the template does not save it. - A failed
infocheck never counts.
On a card with for_each or for_each_from, every copy's checks count, and one copy's
failed error check under errors: fail refuses the whole card, as a strict refusal does.
That includes strict: true on a repeat, which until v2.9.0 did nothing at all on one.
Variables left unset in a repeat's copies still do not make it refuse, and placeholders in
style: are never counted; debug: console
finds those.
- Troubleshooting: reading the debug report, and the error card.
-
Describing Variables:
required:,pattern:andallowed:, which check values in the editor as they are typed. - Configuration Reference: every key on one page.
Getting started
- Home
- Installation
- Quick Start
- Your First Template
- Trying It Out
- Template Builder
- Try a Placeholder
- Try a Template
Core concepts
Content types
Features
- Repeating a Template
- Repeating Sections and Badges
- List Entries
- Page Templates
- Slots
- Templates as Steps
- Sharing Between Dashboards
- Sharing a Template
- Translating a Shared Template
- Visibility
- Checks and Strict
- Styling
- Visual Editors
- Health Card and Badge
- Reading the Debug Report
- Translations
Reference