diff --git a/README.md b/README.md
index ff2bbcb..6541ec9 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,8 @@ Live charge and temperatures, one-tap boost, Energy Dashboard support, PV divert
 
 [![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=CaputoDavide93&repository=Mixergy-Home-Assistant&category=integration)
 
+> **Note — the icon shows as a grey placeholder in HACS.** Nothing is wrong with your install: the icon appears correctly everywhere inside Home Assistant itself. This is a [known HACS limitation](https://github.com/hacs/integration/issues/5171) affecting every custom integration published after February 2026, not an issue with this integration. [More detail](docs/troubleshooting.md#why-is-the-icon-missing-in-hacs).
+
 ---
 
 ## 📚 Documentation
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index a11f819..7827eaa 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -151,6 +151,14 @@ File issues at [github.com/CaputoDavide93/Mixergy-Home-Assistant/issues](https:/
 
 ## ❓ FAQ
 
+### Why is the icon missing in HACS?
+
+HACS shows a grey placeholder instead of the Mixergy icon. **Nothing is wrong with your install** — the icon appears correctly everywhere inside Home Assistant itself (Settings → Devices & Services, the device page, and every entity).
+
+It is a known HACS limitation, not an issue with this integration. Since Home Assistant 2026.3 custom integrations ship their brand images inside the integration (this one does — `custom_components/mixergy_tank/brand/`), and `home-assistant/brands` no longer accepts submissions from custom integrations. The HACS dashboard still reads icons from that older brands CDN, so any custom integration published after February 2026 shows a placeholder there.
+
+There is nothing to fix on your side and no effect on functionality. Tracked upstream at [hacs/integration#5171](https://github.com/hacs/integration/issues/5171), with a fix proposed in [hacs/integration#5388](https://github.com/hacs/integration/pull/5388).
+
 ### Does this work without internet, or locally?
 
 No. This is a cloud-polling integration for the official Mixergy API at `www.mixergy.io` — the tank has no supported local API, so every reading and every command goes through Mixergy's cloud. If your internet connection or Mixergy's service is down, entities go unavailable until it recovers.