Troubleshooting

Troubleshooting

Work down the list — the first two fix most things.

---

The card does not appear at all

"Custom element doesn't exist: decluttering-card-plus"

1. Hard refresh. Ctrl+Shift+R, or Cmd+Shift+R on a Mac. Browsers cache dashboard resources aggressively and this is the single most common cause.
2. Check the resource is registered. Settings → Dashboards → ⋮ → Resources. There should be an entry for decluttering-card-plus.js with type JavaScript module.
3. Check the file is actually served. Open the resource URL directly — e.g. http://homeassistant.local:8123/local/decluttering-card-plus.js. You should get JavaScript, not a 404.
   • A 404 for a /local/ URL usually means config/www did not exist when Home Assistant started. Restart Home Assistant.
4. Check the console (F12). The card announces itself on load:

    DECLUTTERING-CARD-PLUS
      Version …
   

   If that line is missing, the file is not being loaded at all.

The general Lovelace plugin guide is also worth a read: Troubleshooting Lovelace plugins.

---

[[something]] appears on the card

A placeholder with no value is left in place, so you see the literal text — or Home Assistant complains about an unknown entity called [[light]].

Causes, in order of likelihood:

1. Typo. The name in the template and the name in variables must match exactly, and they are case sensitive. [[Light]] ≠ [[light]].
2. variables written as a mapping instead of a list.

   variables:
     - light: light.kitchen    # ✅

   variables:
     light: light.kitchen      # ❌

3. No default and nothing passed. Add it to the template's default.

Seeing [[light]] with "Unknown entity selected" inside the template editor is expected — that editor is looking at the raw template. See Visual Editors.

---

"The template … doesn't exist"

The name could not be found on this dashboard.

• Check the spelling against the template's name.
• Check where you defined it. decluttering_templates must be at the root of the dashboard config, level with views: — not inside a view.
• Check which dashboard. Templates are per dashboard. A template on your main dashboard is invisible to your tablet dashboard unless you borrow it.
• If the message mentions decluttering_templates_from, the borrowed dashboards were read and did not contain it either. Check the console for could not read the dashboard "…", and check the URL path against Settings → Dashboards — it is the path in the address bar, not the title.

---

"You must define one card, badge, element, or row in the template"

A template must contain exactly one of card, badge, row, element.

# ❌ two content keys
my_template:
  card:
    type: tile
  row:
    entity: sensor.x

# ❌ none - the content is at the wrong level
my_template:
  type: tile
  entity: sensor.x

# ✅
my_template:
  card:
    type: tile
    entity: sensor.x

---

"The list of variables must be an array of key and value pairs"

variables (and default) must be a list. Every entry needs a leading -.

variables:
  - light: light.kitchen
  - room: Kitchen

---

Invalid YAML around a variable

entity: [[light]]      # ❌
entity: '[[light]]'    # ✅

A [ at the start of a value begins a YAML list, so an unquoted placeholder that is the whole value is a syntax error. Inside a longer string it is fine unquoted.

---

A number is being treated as text

Make sure the placeholder is the entire value:

grid_options:
  columns: '[[cols]]'          # ✅ whole value - stays a number

grid_options:
  columns: 'col-[[cols]]'      # ❌ part of a string - becomes text

See Variables.

---

My CSS does nothing

Almost always because the selector cannot cross a shadow boundary.

style: |
  ha-card { border: 2px solid red; }       # ❌ never matches

style: |
  :host {
    --ha-card-border-color: red;
    --ha-card-border-width: 2px;
  }                                        # ✅

Style Home Assistant cards through CSS custom properties. Full explanation and a table of what does and does not reach the card: Styling.

---

Changes to a borrowed template are not showing

Borrowed dashboards are read once per page load and cached. After editing a template on the source dashboard, refresh the browser on the dashboards that borrow it.

See Sharing Templates Between Dashboards.

---

"gave up substituting variables after 10 passes"

A variable refers to itself, directly or through a chain:

default:
  - name: [[name]] light'     # ❌ refers to itself

default:
  - a: '[[b]]'
  - b: '[[a]]'                 # ❌ cycle

Break the loop by introducing a separate name:

default:
  - label: [[name]] light'    # ✅
  - name: Kitchen

---

"… is already registered by something else, skipping it"

Another card owns that type — normally the original decluttering-card running alongside this one. Everything still works, but you are getting the other card's behaviour for custom:decluttering-card. Remove the original: see Migrating from decluttering-card.

---

"Could not retrieve the lovelace configuration."

The card could not find the dashboard configuration to read templates from. This happens where there is no normal Lovelace dashboard around the card — some kiosk and embedding setups, for example. Casting is handled.

---

A templated card is the wrong size in a sections view

Set grid_options inside the template's card, not on the custom:decluttering-card-plus instance. The card reports the wrapped card's options to the layout, so they belong with the card they describe. See Cards.

---

A picture-elements marker is in the wrong place

Positioning (top, left) goes on the instance, in the elements: list. Appearance goes in the template. Both are called style, which is confusing — Elements has a table.

Remember that Picture Elements positions by the top-left corner. Add transform: translate(-50%, -50%) to centre on the point.

---

Still stuck

Open an issue at tempus2016/decluttering-card-plus/issues with:

• your template definition and the card that uses it,
• what you expected and what you got,
• anything from the browser console (F12),
• your Home Assistant version and how you installed the card.