HACS downloads panel shows 'icon not available' for custom integrations shipping inline brand icons (HA 2026.3+ brands proxy)

[iskael]

Web browser

Chromium-based (Chrome/Edge) and Firefox — any recent browser

Web browser version

Reproduces on all current browsers; the bug is a static code gap in the HACS frontend bundle, not a browser-specific rendering issue

System Health details

• Home Assistant: 2026.4.2
• HACS integration: 2.0.5 (latest release, confirmed up to date via `update.hacs_update`)
• HACS frontend bundle: latest published release is `20250128065759` (Jan 28, 2025)
• Custom integration reproducing the issue: `iskael/bosch-dishwasher`, which ships inline brand icons under `custom_components/bosch_dishwasher/brand/` per the new API

Checklist

• I'm running the newest version of HACS
• I have filled out the issue template to the best of my ability
• I have read https://hacs.xyz/docs/help/issues/
• This issue is related to the frontend of HACS
• This issue only contains 1 issue
• This is a bug and not a feature request
• This issue is not a duplicate

Describe the issue

Starting with Home Assistant 2026.3, custom integrations can ship their own brand icons directly inside the integration (`custom_components//brand/icon.png`), and HA serves them through a new authenticated proxy at `/api/brands/integration//`. See the official announcement: https://developers.home-assistant.io/blog/2026/02/24/brands-proxy-api. The `home-assistant/brands` repository now auto-closes any PR for `custom_integrations/*` and tells contributors to use the inline mechanism instead.

The problem is that the HACS frontend still hits the public CDN for custom-integration icons, so inline brands are invisible in the HACS downloads panel — the row shows the "icon not available" placeholder even though the icon is correctly served by the local proxy.

Root cause (verified against the source):

`src/dashboards/hacs-dashboard.ts` imports `brandsUrl` from the pinned `homeassistant-frontend` submodule and calls it like this:

```ts
<img
src=${brandsUrl({
domain: repository.domain || "invalid",
type: "icon",
useFallback: true,
darkOptimized: this.hass.themes?.darkMode,
})}
/>
```

`useFallback` is a field from the old `BrandsOptions` interface that no longer exists in `home-assistant/frontend` `dev`. The current implementation was rewritten for the brands proxy:

```ts
// home-assistant/frontend/src/util/brands-url.ts (current)
export const brandsUrl = (options: BrandsOptions, hassUrl?: string): string => {
hassUrl = hassUrl ?? location.origin;
const base = `/api/brands/integration/${options.domain}/${
options.darkOptimized ? "dark_" : ""
}${options.type}.png`;
const url = new URL(base, hassUrl);
if (_brandsAccessToken) {
url.searchParams.set("token", _brandsAccessToken);
}
return url.toString();
};
```

HACS's pinned submodule is still on the old version that returns `https://brands.home-assistant.io/_/{domain}/icon.png\` directly to the browser. That CDN path doesn't serve inline-shipped custom-integration icons, so custom integrations on HA 2026.3+ that use the new mechanism get the placeholder.

Also worth noting: the maintainers of `home-assistant/brands` already redirect contributors here. Closed PR home-assistant/brands#10149 from this thread was auto-closed with the exact message "we no longer accept brand icons for custom integrations in this repository".

Reproduction steps

1. Run Home Assistant 2026.3.0 or newer (reproduced on 2026.4.2).
2. Install any custom integration that ships brand icons inline under `custom_components//brand/icon.png`. A minimal example is `iskael/bosch-dishwasher` (v0.1.4 and later).
3. Confirm that HA core renders the icon in Settings → Devices & services (it does — served via `/api/brands/integration//icon.png` with an auth token).
4. Open HACS → Downloads and look at the row for that integration.
5. The row shows the generic "icon not available" placeholder instead of the inline icon.

Direct verification against the HA instance:

```

200, image/png, matches the bytes of brand/icon.png

curl -H "Authorization: Bearer " \
http://HA/api/brands/integration/bosch_dishwasher/icon.png

→ 200, image/png, 2515 bytes

without the token the proxy returns 403

curl http://HA/api/brands/integration/bosch_dishwasher/icon.png

→ 403

```

Screenshots

The same integration renders its icon correctly in HA core's integration list and on the config-flow dialog — the gap is specific to the HACS panel.

Javascript logs from your browser console

No runtime errors. The bug is a static code gap: the bundled `brandsUrl` returns the old CDN URL (`https://brands.home-assistant.io/_/bosch_dishwasher/icon.png\`), the browser requests it, the CDN responds 404, and HACS's `` falls back to the placeholder. No exceptions are thrown.

Debug logs

Not applicable. This is not a runtime error in the integration; it is reproducible by reading the source of `src/dashboards/hacs-dashboard.ts` and the pinned `homeassistant-frontend` submodule. Enabling HACS debug logging produces no additional information because the icon resolution happens entirely on the frontend.

Diagnostics dump

Not applicable for the same reason — the HACS integration diagnostics do not cover frontend bundle paths. Happy to provide one if the maintainers believe it would add information.

Requested change

1. Bump the pinned `homeassistant-frontend` submodule past the brands-proxy rewrite (so `brandsUrl` points at `/api/brands/integration/...` and uses the access token flow).
2. In `src/dashboards/hacs-dashboard.ts`, drop `useFallback: true` (no longer a valid `BrandsOptions` field) and call `fetchAndScheduleBrandsAccessToken(this.hass)` during panel initialization so `` URLs carry a valid `?token=...` query string.
3. Cut a new HACS frontend release — the last published one is `20250128065759`, which predates the HA 2026.3 brands-proxy feature.

With those three changes the HACS panel will pick up inline brand icons automatically, no PR to `home-assistant/brands` required (which is the officially supported path now).

[hacs-bot]

Thank you for opening an issue in the HACS.

Before proceeding, please verify the following:

Select the correct issue template:
HACS provides different templates for different types of bugs. Choosing the right template ensures you're asked the right questions and helps route your bug appropriately.

Complete the ENTIRE issue template:
Make sure you've read the issue guidelines and filled out every single field in the issue template, even if some fields seem unrelated to your specific situation.

Fill out everything, even if it seems unnecessary:
Don't skip fields because they "don't seem relevant" to your bug. The template asks for specific information because:

• Problems often have unexpected causes that surface through "unrelated" details
• What seems unrelated to you might be the key to solving your bug
• Incomplete information requires follow-up questions, delaying resolution
• The template is designed based on years of troubleshooting experience
• Missing information forces those helping to make assumptions, which can lead to wrong solutions

Issues with incomplete templates take significantly longer to resolve or may be closed without resolution.

If you're experiencing a similar bug:
If your bug is identical to an existing one, please:

• Add a 👍 reaction to the original issue description
• Subscribe to notifications on that issue to stay updated
• Do not add comments like "same here", "I have this too", or "+1"

Adding duplicate comments creates noise and makes it harder to track and resolve issues. Reactions help prioritize issues based on how many users are affected.

Getting help:
If you need assistance filling out the template or understanding your issue:

• Issue Guidelines - Detailed instructions for reporting issues
• HACS Discord - Community support and real-time help

What happens next:
Maintainers and community members will review your issue and may:

• Ask for additional information if the template is incomplete
• Provide a solution or workaround
• Label the issue appropriately for tracking
• Link it to related issues or pull requests

[manuveli]

#5228
hacs/frontend#937

Delivered integration and frontend fix for this, hope it gets merged soon.

[yellowcooln]

Another concrete reproduction:

• Custom integration repo: https://github.com/pyMC-dev/pyMC-HA-Integration
• Domain: pymc_repeater
• Home Assistant shows the icon correctly from the integration-local brand folder.
• HACS still shows the icon not available placeholder for the repository card.

Why this appears inconsistent with some other integrations:

• meshcore-dev/meshcore-ha works in HACS because meshcore already exists in home-assistant/brands.
• pymc_repeater does not exist there, and new PRs for custom integrations are now auto-closed by home-assistant/brands.

I verified that directly by opening:

• home-assistant/brands PR: Add pyMC Repeater brand assets home-assistant/brands#10230

The bot response there says custom integrations must now ship local brand assets instead of adding entries to home-assistant/brands, which pymc_repeater already does.

So this repo is another example where:

1. local custom_components/<domain>/brand/ assets are correct
2. Home Assistant itself renders them correctly
3. HACS still resolves the placeholder because it is not using the local brands proxy path for this dashboard view

[svilendotorg]

Confirming this affects HaSeerr as well:

• Repo: https://github.com/svilendotorg/haseerr
• Brand assets at custom_components/haseerr/brand/ + repo root
• Icon works on HA Integrations page (brands proxy API) but shows "icon not available" in HACS downloads panel
• Testing on HA 2026.4.4 + HACS 2.0.5

Related: commented on #5171 with same confirmation.