HACS and Customization

Why Your HACS Cards Aren't Showing Up in Home Assistant

HACS cards often fail to show because the dashboard resource is missing, stale or the wrong type. Here are the fixes, from a hard refresh to a manual resource.

On this page
  1. Start with a hard refresh
  2. Check the dashboard resource
  3. Fix the resource type
  4. YAML-mode dashboards
  5. Remove duplicate or stale resources
  6. Read the browser console
  7. Card missing from the picker
  8. When it still fails
  9. Common misconceptions

If you installed a card through HACS and it doesn’t appear, or your dashboard shows “Custom element doesn’t exist”, the card’s file usually isn’t loaded. Downloading a card in HACS does not put it on a dashboard. You still add the card, and the dashboard has to load the card’s file.

Start with a hard refresh

Most of the time, a cached frontend is the cause. Hard-refresh the browser:

  • Windows or Linux: Ctrl+F5 or Ctrl+Shift+R
  • Mac: Cmd+Shift+R

In the Home Assistant Companion app, go to Settings > Companion App > Debugging, select Reset frontend cache, then restart the app.

A Home Assistant restart usually doesn’t fix a cached frontend, so clear the browser cache first.

Check the dashboard resource

Each card needs a dashboard resource entry that points to its file.

  • Storage-mode dashboards (the ones you edit in the UI): HACS adds the resource for you.
  • YAML-mode dashboards: you add the resource yourself, as described below.

To view the resources:

  1. Turn on Advanced Mode in your user profile.
  2. Go to Settings > Dashboards, open the three-dot menu, and select Resources.

Each entry should use the URL /hacsfiles/<repo-name>/<file>.js and the type JavaScript module. HACS stores the files in /config/www/community/<repo-name>/, and /hacsfiles/ maps to that folder. Note that /local/ and /hacsfiles/ are not interchangeable for HACS-managed files.

Fix the resource type

The type must be JavaScript module. Older entries registered as plain JavaScript can fail with newer cards. If the type is wrong, edit the entry, change it to the module type, and save.

YAML-mode dashboards

If your dashboard is in YAML mode, add the resource to configuration.yaml under lovelace:, with type: module:

lovelace:
  resources:
    - url: /hacsfiles/my-card/my-card.js
      type: module

Use the file name that HACS installed for your card, then restart Home Assistant. Card resources in YAML mode don’t reload until you restart.

Remove duplicate or stale resources

Old ?hacstag= entries, or manual copies of a card in /local/, can conflict with the HACS version. Keep one resource entry per card, and delete the rest.

Read the browser console

Press F12 to open the browser’s developer tools, then look at the Console and Network tabs. A 404 error for the resource means the file path is wrong. A JavaScript error usually points to the card’s own code.

“Custom element doesn’t exist: X” means one of two things. Either the resource isn’t loaded, or the card type name is misspelled. In YAML, card types need the custom: prefix, such as type: custom:mushroom-entity-card.

Card missing from the picker

Some cards don’t appear in the card picker. You can still add them by choosing the Manual card, which takes YAML. Use the card’s documented type name.

When it still fails

If the card still doesn’t load:

  1. Uninstall the card in HACS.
  2. Remove its resource entry from the dashboard’s resources.
  3. Restart Home Assistant.
  4. Reinstall the card in HACS, then add the resource back once.
  5. Clear the browser cache and refresh the dashboard.

Frontend updates can also break older cards. Check the card’s issue tracker and update the card in HACS.

Common misconceptions

  • “Downloading a card puts it on my dashboard.” It doesn’t. You still add the card to a dashboard.
  • “A restart will fix a cached frontend.” Usually it won’t. Clear the browser cache.
  • “Integrations from HACS are cards.” They are not. Integrations appear under Settings > Devices & services after a restart.

For the HACS install steps, see our HACS guide. For card picks, see popular HACS repositories.

The complete guide to hacs and customization

What Is HACS and How to Install It in Home Assistant
Read the guide

Keep exploring

Guides from other topics

All topics →