HACS: When Custom Integrations Bite You

It Was Working Fine Yesterday

You know the feeling. You run the monthly Home Assistant core update, grab a coffee, come back to a dashboard that looks like someone fed it through a shredder. Five Lovelace cards are throwing errors. One custom integration refuses to load entirely. HA’s log is screaming about an incompatible API call in a component whose last commit was eight months ago.

The culprit? HACS — the Home Assistant Community Store. Or more precisely, the part where you installed a bunch of community components, said “I’ll keep an eye on these,” and then absolutely did not keep an eye on these.

This is the HACS story nobody tells you when they’re showing off their gorgeous mushroom-card dashboard.

What HACS Actually Is (And Isn’t)

HACS is a third-party add-on for Home Assistant that lets you install community-built integrations, Lovelace cards, themes, and Python scripts directly from GitHub repositories. It’s genuinely useful. Without it, you’d be manually cloning repos, copying files, and editing paths like it’s 2015.

But here’s what HACS is not: an official marketplace. There’s no sandboxing, no automated security scanning, no compatibility guarantee, no Anthropic-style red team review. It’s GitHub repos, all the way down.

HACS has two tiers of content:

• Default repositories — curated by the HACS maintainers. These have at least passed a basic quality bar: they have a valid hacs.json, they respond to issues, they’re not obviously abandoned. Still community code, but lightly vetted.
• Custom repositories — anything you add manually by pasting a GitHub URL. Zero vetting. You’re trusting a stranger’s repo unconditionally.

Most people use the default repos and assume that means “safe.” It means “not obviously broken when someone looked at it.” That’s a narrower guarantee than you think.

The Update Model Is the Real Problem

Here’s the actual footgun: HACS installs are essentially HEAD of whatever branch the author configured. You get a notification in the HACS panel when there’s a new release, and you can click “Update All” like a responsible adult — or ignore it for four months because updating stuff is scary.

Both approaches have failure modes.

Update immediately: The author pushed a breaking change. Your dashboard is now broken on a Saturday morning when your partner wants to check if the robot vacuum is running.

Update never: HA core ships a new version that changes an internal API. The six-month-old component that calls that API breaks silently or loudly depending on the author’s error handling. Your dashboard breaks on a Saturday morning anyway.

There’s no built-in pinning to a specific release in HACS the way you’d pin a Python package version. Some components support it via the HACS config, but most don’t, and the UI doesn’t make this obvious. You’re broadly at the mercy of upstream release cadence matching HA’s release cadence. When they don’t align — and they often don’t — you get breakage.

Components That Are Actually Trustworthy

Before I sound like a HACS hater: it has genuinely excellent components that behave like first-class citizens. The key signals are active maintenance, large user bases, and clean separation from internal HA APIs.

Adaptive Lighting — Probably the gold standard of HACS components. Adjusts color temperature and brightness based on circadian rhythm. Maintained actively, proper CI, handles HA API changes quickly. It’s so good that there’s been recurring discussion about merging it into HA core. Use this.

Mushroom Cards — A full Lovelace card library with a clean, modern design system. Huge install base, responsive maintainers, regular updates that track HA releases. Your dashboards will look dramatically better. Low risk.

mini-graph-card — The sensor history graph card HA ships with is functional but ugly. mini-graph-card does it better, with more options. Been around long enough that it’s stable and battle-tested.

Browser Mod — Lets HA interact with the browser directly: popups, navigate to views, play sounds, set device-specific settings. More complex integration model, but maintained well and widely deployed.

These components are popular enough that when something breaks, it gets fixed within days, not months. Community size is a proxy for maintenance quality. A component with 12,000 installs has a very different bug response time than one with 340.

The Components That Will Eventually Betray You

Some categories of HACS components are structurally risky regardless of how well-maintained they seem today.

Third-party vendor integrations that aren’t officially supported — Tesla custom integrations, Ring doorbell scrapers, certain EV charger components. These work by reverse-engineering mobile app APIs or scraping endpoints the vendor doesn’t document. When the vendor updates their app (which they do constantly), the integration breaks. Sometimes for days. Sometimes forever until someone reverse-engineers the new API.

Anything touching cloud authentication — If a component is storing OAuth tokens to talk to a cloud service through unofficial channels, you’re one vendor-side change from having it stop working and potentially having stale tokens floating around in your config.

DOM-scraping browser integrations — Components that pull data by scraping a website’s HTML structure rather than using an API. The HTML changes; the component breaks. There’s no graceful degradation, usually just an exception in the log and missing data.

Single-maintainer repos with low commit frequency — Check the GitHub before you install. If the last commit was 11 months ago and there are 40 open issues with no responses, that’s your answer. It works today. HA 2026.7 might change that.

# Before installing any HACS component, check its health
# Look at: last commit, open vs closed issue ratio, release frequency
# There's no CLI for this — just use the GitHub UI before you install

The honest advice: if the official HA integration for a service exists and is even marginally functional, use it. The official integration gets updated when HA internals change. The community one gets updated when someone gets around to it.

When Custom Integrations Break Boot

This is the nightmare scenario: a custom integration has a bug that causes an exception during HA startup. Not just “this card doesn’t load” — HA refuses to start at all. You’re staring at a loading spinner that never resolves.

Here’s how to recover without restoring a snapshot.

Step 1: SSH in or use the terminal add-on

# If HA is in a Docker container
docker exec -it homeassistant /bin/bash

# Or SSH to your HA host if you have it set up
ssh [email protected]

Step 2: Locate and remove the broken component

Custom integrations live here:

ls /config/custom_components/
# You'll see folders like: tesla_custom, ring_doorbell_hacs, whatever_broke_you

The HA log (before it dies) will tell you which component failed. If you can’t read the log because HA won’t start, look for the most recently modified folder — that’s usually the culprit.

# Find recently modified custom components
ls -lt /config/custom_components/ | head -10

# Remove the broken one
rm -rf /config/custom_components/broken_integration_name

Step 3: Restart

# In Docker
docker restart homeassistant

# On HA OS
ha core restart

HA will start without that integration. You’ll have to fix the component or remove references to it from your configuration.yaml and Lovelace dashboards.

Step 4: Clean up configuration references

# If the broken integration had config here, comment it out
# before restarting — otherwise HA might throw errors even without the component

# broken_integration:
#   api_key: !secret broken_api_key
#   something: else

Snapshot Before Everything, Always

This should go without saying, but given how many people skip it: take a snapshot before every HA core update and before every batch of HACS updates.

# On HA OS — trigger a backup via CLI
ha backups new --name "pre-update-$(date +%Y%m%d)"

# In Docker — just copy the config directory
cp -r /path/to/homeassistant/config /path/to/homeassistant/config.bak.$(date +%Y%m%d)

HA OS has built-in backup scheduling. Use it. Point it at network storage or cloud. A backup sitting only on the same machine as HA is not a backup — it’s a coincidence.

If you’re serious about this, add the Auto Backup HACS integration (yes, using HACS to manage backups has a certain irony). It runs scheduled backups and can upload to Google Drive, OneDrive, or local NAS automatically.

Staging Changes in a Dev Environment

If you run a reasonably important Home Assistant instance — controlling locks, alarms, HVAC, things that need to reliably work — you should have a staging environment.

The easiest approach is Docker on your existing server:

services:
  homeassistant-dev:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: ha-dev
    volumes:
      - ./ha-dev-config:/config
    ports:
      - "8124:8123"
    environment:
      - TZ=America/New_York
    restart: unless-stopped

Copy your production config in, install the HACS update there first, verify nothing explodes, then update production. This takes maybe 20 minutes to set up and has saved me many Saturday mornings.

You can also use the Home Assistant development container for testing specific integrations:

# Pull the beta/dev build to test compatibility ahead of time
docker pull ghcr.io/home-assistant/home-assistant:beta

When to Skip HACS Entirely

Honest take: if your Home Assistant setup needs to be spouse-grade reliable — meaning the person you live with will notice and be annoyed when automations fail — reconsider how much custom stuff you pile on.

Every HACS component you install is a dependency with its own update cadence and its own failure mode. One per category is usually fine. Ten across every area of your config is a combinatorial explosion of things that can break simultaneously during an HA core update.

Signs you should probably skip HACS or minimize it:

• You don’t have time to maintain it (check updates, read changelogs, test before applying)
• Your HA instance controls things that genuinely matter: heating, medical equipment, door locks in a serious security context
• You’re not comfortable SSHing into your host and editing files when something breaks
• The official HA integration exists and is “good enough” — good enough always beats perfect-but-fragile

For most of us, the sweet spot is: use HACS for UI components (Mushroom, mini-graph-card, Adaptive Lighting) and avoid it for cloud-dependent custom integrations where an official integration exists. The Lovelace cards break gracefully (a card shows an error, HA still runs). A broken custom integration can take the whole instance down.

Version Pinning: The Limited Options

HACS doesn’t offer first-class version pinning through its UI as of 2026. You can manually install a specific release by:

1. Going to the component in HACS
2. Clicking the three-dot menu
3. Selecting “Redownload” — which lets you pick a version from GitHub releases

This is clunky but functional for rolling back a bad update. For staying on a specific version, you’d need to remove the HACS-managed version and manually copy the files from GitHub, which defeats the convenience purpose.

The practical solution most people land on: update HACS components in small batches rather than “Update All,” and always do it before a weekend when you can fix things if they break.

The Bottom Line

HACS is a power tool, and power tools are great until you’re not paying attention. The default-repo components have earned their place — Mushroom Cards, Adaptive Lighting, mini-graph-card, and Browser Mod are genuinely better than the stock alternatives. Use them.

Get more cautious as you move toward custom repos, single-maintainer integrations, and anything that depends on undocumented vendor APIs. These are the ones that will break at the worst time for the most annoying reasons.

Take snapshots. Stage updates. When in doubt, check whether an official HA integration exists first. And if your partner is about to turn off the lights manually because the automation broke again — maybe that’s the universe telling you to thin the custom component herd.

Your future 2 AM self — the one who just updated HA before bed — will appreciate having followed at least half of this advice.