docs: troubleshooting «Invalid handler specified» (нет pyfglair / нет перезапуска)

- README компонента: проверка лога, установка pyfglair в окружение HA
  (docker exec python -m pip), полный перезапуск, проверка импорта
- RELEASE_HA: та же диагностика в разделе установки
This commit is contained in:
2026-09-29 16:13:19 +03:00
parent 8a073d96a6
commit 49d5533cd1
2 changed files with 35 additions and 0 deletions
+28
View File
@@ -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 появится