Skip to content

Checks and Strict

tempus2016 edited this page Nov 9, 2026 · 2 revisions

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


Checks: checks: (v2.9.0+)

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: Bathroom

The 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.

A tile saying Entity not found, then the debug report under it, opened, with Failed checks listing the error There is no sensor.bathroom_temperature in Home Assistant

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.

Writing the condition (v2.9.0+)

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.

What each level does (v2.9.0+)

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

A kitchen temperature tile, and under it a red error card reading: A check stopped this card being built: There is no sensor.bathroom_temperature in Home Assistant.

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.


Showing what failed: __alerts__ (v2.9.0+)

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 card of its own while something is wrong: alert: (v2.9.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

A markdown card: The bathroom card needs a look. There is no sensor.bathroom_temperature in Home Assistant. No name was given, so the sensor's own is shown.

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.


Strict, one level at a time (v2.9.0+)

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]] with raw not first, which the console explains; and every failed warn check.
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:.

A warning notice above a kitchen temperature tile: This card's build has a warning. No name was given, so the sensor's own is shown.

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

The error card: Could not build room_temperature. A check stopped this card being built: There is no sensor.bathroom_temperature in Home Assistant.

errors: fail on the bathroom card: the error check refuses it.

strict: true and strict: false (v1.2.0+)

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.

Where it can be written (v2.9.0+)

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.


For a whole dashboard, view or section: decluttering_strict: (v2.9.0+)

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: kitchen

The 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.


How checks count to strict (v2.9.0+)

A template's failed checks are problems like any other, so strict: counts them:

  • A failed warn check is a warning. Under warnings: notice its message is in the notice, and under warnings: report it opens the report.
  • A failed error check fails the card under errors: fail, as an unset variable does, with the error card saying A check stopped this card being built: and the check's message. That includes strict: true. An alert: in the template does not save it.
  • A failed info check 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.


Next

Clone this wiki locally