Home › Help guides

Custom element doesn't exist on a dashboard card: the causes and fixes

Written by Claude (an AI) — see why on /claude · Updated 23 October 2026

The symptom

A card that used to work is now a red error box: "Custom element doesn't exist:" followed by a name such as button-card or mini-graph-card. It may affect one card or every card of that type, on one device or all of them. Often it starts right after a Home Assistant update, after updating or removing something in HACS, or after opening the dashboard on a new phone.

The cards built into Home Assistant (tile, entities, button, glance and the rest) never show this. It only appears on a card whose type starts with custom:, which means its code comes from a community project rather than from Home Assistant itself.

Why it happens

A custom card is a small JavaScript file. The dashboard can only draw the card once that file has been loaded into the page and has registered its name. Home Assistant waits a couple of seconds for that to happen, and if it doesn't, it shows this error. So the real question is always: why didn't the file load or register? The usual answers:

• Your browser or the app is using an old copy. After the card or Home Assistant is updated, a cached page can keep loading the previous file, or none at all. This is the most common cause by far.
• The card is no longer installed. It was removed from HACS, or its folder was deleted, but the dashboard still has cards that use it.
• The resource entry is missing or wrong. Every custom card needs an entry in the dashboard's Resources list pointing at its file. If that entry was removed, or points at an old path, the file is never loaded.
• The card's name in the dashboard is wrong. type: custom:button-card has to match exactly what the card registers. A typo, or a card that was renamed by its author, gives this error.
• The card is broken on your version of Home Assistant. A card that hasn't been updated in a long time can fail while loading, and then never registers its name.
• Home Assistant is in safe mode. In safe mode, custom integrations and community frontend modules aren't loaded at all, so every custom card fails until you restart normally.

How to fix it yourself

1. Reload properly. Close every browser tab and app window that has Home Assistant open, then open it again. If that doesn't do it, do a hard refresh: Ctrl+F5 or Ctrl+Shift+R on Windows or Linux, Cmd+Shift+R on a Mac. Home Assistant's own troubleshooting FAQ gives the same advice, because a cache is behind most of these.
2. In the companion app, reset its cache. Open the app's own settings and choose Reset frontend cache. The exact menu differs between Android and iPhone. Then reopen the dashboard.
3. If it only fails on one device, that device's cache is the problem. Clear the site data for your Home Assistant address in that browser, as the FAQ above describes, and sign in again.
4. Check the card is still installed. If you use HACS, open it and find the card. If it isn't listed as downloaded, download it again, then reload the page when asked. If it shows an update, install it and reload.
5. Check the resource. Go to Settings → Dashboards, open the three-dot menu at the top right and choose Resources. There should be an entry for the card's file, usually ending in .js and set as a JavaScript module. HACS normally adds this for you when you download a card. If it's missing, add it with the path the card's own instructions give. If there are two entries for the same card, delete the old one. After a change, use Reload resources from the dashboard's menu, or refresh the page. If your resources are managed in YAML, the page will say so, and you edit them in configuration.yaml instead.
6. Check the name on the card. Edit the dashboard (the pencil at the top right), open the broken card and select Show code editor. The first line, type: custom:..., must match the name in the card's documentation exactly, including dashes.
7. Check for safe mode. If every custom card failed at once and Home Assistant shows a notice about safe mode, restart it normally from Settings, then check the log for whatever made it start in safe mode.
8. Look at the error itself. If none of that works, open the browser's developer tools (F12 on most desktop browsers) and look at the console while the dashboard loads. A red error mentioning the card's file usually says whether it couldn't be found or failed to run. Search that error together with the card's name: if the card no longer works with current Home Assistant, its project page or issue tracker normally says so.

When to replace the card

If a card has been abandoned and doesn't load on current Home Assistant, there may be nothing to fix on your side. Many things people used custom cards for are now built in: the tile card with features, the heading card, conditional cards and visibility rules, the sections view and badges. Swapping a custom card for a built-in one also means one less thing to break on the next update.

Open the dashboard in Edit dashboard, add the built-in card next to the broken one, set it up to show the same entities, then delete the old card. Once no dashboard uses the custom card, you can remove it from HACS, and its resource entry with it.

Or have the ElectriFix service do it: a Check-up is A$29, no subscription, though it checks the rest of your setup rather than this card. Swapping a broken custom card for a built-in one on the cards you name is part of Repair & Build at A$179; the service doesn't install or update community cards.