diff --git a/custom_components/fglair/README.md b/custom_components/fglair/README.md
index a8a3bec..518dfa3 100644
--- a/custom_components/fglair/README.md
+++ b/custom_components/fglair/README.md
@@ -126,6 +126,34 @@ lanip_key_id) или импорт `config_*.json` от `fglair-discover`/`fglctl
 
 ## Диагностика и известные ситуации
 
+* **«Не удалось загрузить мастер настройки: Invalid handler specified»** —
+  HA не смог импортировать компонент (обычно нет пакета `pyfglair`).
+  Проверьте лог HA:
+
+  ```sh
+  grep -iE "fglair|pyfglair" /config/home-assistant.log | tail -20
+  # ожидаемая причина: ModuleNotFoundError: No module named 'pyfglair'
+  ```
+
+  Установите пакет в то же python-окружение, в котором работает HA, и
+  **полностью перезапустите** HA (не только интеграцию):
+
+  ```sh
+  # HA OS / Supervised (SSH add-on с доступом к docker):
+  docker exec homeassistant python -m pip install --no-deps \
+      --index-url https://<user>:<token>@git.ratigorsk-12.ru/api/packages/<owner>/pypi/simple \
+      pyfglair
+  docker restart homeassistant
+
+  # HA Core в venv:
+  /srv/homeassistant/bin/python -m pip install --no-deps --index-url ... pyfglair
+  systemctl restart home-assistant@homeassistant
+  ```
+
+  Проверка: `docker exec homeassistant python -c "import pyfglair; print(pyfglair.__version__)"` — должно печатать версию без ошибок.
+  Другие причины той же ошибки: компонент лежит не в
+  `<config>/custom_components/fglair/` (лишняя вложенность каталогов, нет
+  `__init__.py`), либо HA не перезапускался после копирования.
 * **503 / оба слота заняты** — в LAN уже две сессии (телефон + ESPHome).
   Освободите один слот и перезапустите интеграцию.
 * **key_error** — LAN-ключ не совпал (`key_id` изменился). В HA появится
diff --git a/docs/RELEASE_HA.md b/docs/RELEASE_HA.md
index 870df2d..602c3fa 100644
--- a/docs/RELEASE_HA.md
+++ b/docs/RELEASE_HA.md
@@ -57,6 +57,13 @@ Workflow собирает `wheel` + `sdist`, прогоняет smoke-тест 
   тогда HA сам поставит `pyfglair` из манифеста. Учтите риск dependency
   confusion при `--extra-index-url` — для внутреннего стенда допустимо.
 
+Если при добавлении интеграции HA пишет «Invalid handler specified» —
+пакет `pyfglair` не установлен (или компонент не перезапущен). Смотрите
+`grep -iE "fglair|pyfglair" /config/home-assistant.log`: при
+`ModuleNotFoundError: No module named 'pyfglair'` установите пакет в
+окружение HA (`docker exec homeassistant python -m pip install ...`) и
+полностью перезапустите HA.
+
 * **Публичный PyPI** — см. §2 (для распространения вне сети).
 
 ### 1.3. Обновление интеграции