Integracja w Home Assistant nie ładuje się po restarcie: jak znaleźć i naprawić błąd

Co dokładnie znaczy „integracja nie ładuje się”

Po restarcie Home Assistant integracja może zachowywać się na trzy różne sposoby i każdy z nich ma inną przyczynę. Zanim zaczniesz szukać błędu, otwórz Ustawienia → Urządzenia oraz usługi i zobacz, co jest napisane na karcie integracji.

Encje oznaczone jako „unavailable” zaraz po restarcie to jeszcze nie awaria. Urządzenia Zigbee na baterii, chmurowe API czy kamery potrzebują chwili, żeby się zgłosić. Jeśli po kilku minutach stan się nie zmienia, przejdź do diagnostyki.

Diagnostyka krok po kroku

1. Naprawy i powiadomienia. W Ustawienia → System → Naprawy HA zbiera problemy, które sam rozpoznał: przestarzałą konfigurację YAML, integracje wymagające ponownego logowania, niezgodne integracje niestandardowe. Często już tu jest gotowa odpowiedź z przyciskiem „Napraw”. W menu ⋮ tej samej strony znajdziesz też czasy uruchamiania integracji, które przydają się, gdy start trwa podejrzanie długo.

2. Logi z momentu startu. Ustawienia → System → Logi pokazują pogrupowane błędy. Przełącz widok na pełne logi i szukaj nazwy integracji przy wpisach ERROR i WARNING. Plik home-assistant.log leży w katalogu konfiguracji, a obok niego home-assistant.log.1 z poprzedniego uruchomienia. To przydaje się, gdy chcesz zobaczyć, co działo się tuż przed restartem. Z terminala logi wyświetlisz zależnie od instalacji:

• Home Assistant OS / Supervised: ha core logs
• Docker: docker logs homeassistant (nazwa kontenera może być inna)
• instalacja Core w venv z usługą systemd: journalctl -u z nazwą Twojej usługi

3. Logowanie debug dla jednej integracji. Gdy zwykły log mówi tylko „Error setting up entry”, wejdź w integrację i wybierz z menu Włącz rejestrowanie debugowania. Odtwórz problem (zrestartuj lub przeładuj integrację), a potem wyłącz debugowanie. HA pobierze wtedy plik z pełnym zapisem. Jeśli integracja nie startuje wcale, to samo ustawisz w configuration.yaml:

logger:
  default: warning
  logs:
    homeassistant.components.zha: debug
    custom_components.nazwa_integracji: debug

4. Tryb awaryjny. W menu restartu (Ustawienia → System → ikona zasilania → opcje zaawansowane) jest restart w trybie awaryjnym, a z terminala w HA OS to ha core restart --safe-mode. W tym trybie nie ładują się integracje niestandardowe ani zasoby frontendu spoza HA. Jeśli w trybie awaryjnym wszystko wstaje poprawnie, winna jest prawie na pewno któraś integracja z HACS.

Najczęstsze przyczyny i jak je naprawić

Błąd w pliku YAML

Integracje konfigurowane w configuration.yaml są sprawdzane przy starcie. Jeśli ich sekcja ma błąd, HA pomija tę integrację i zgłasza nieprawidłową konfigurację w powiadomieniach i logach. Najczęstsze przyczyny to tabulator zamiast spacji, przesunięte wcięcie, brak dwukropka albo klucz, który w nowej wersji został usunięty lub przeniesiony do konfiguracji przez interfejs.

Przed każdym restartem po edycji pliku użyj przycisku Sprawdź konfigurację w Narzędzia deweloperskie → YAML. W HA OS to samo robi ha core check, a w Dockerze:

docker exec homeassistant python -m homeassistant --script check_config --config /config

Wiele zmian w YAML nie wymaga pełnego restartu. W tym samym miejscu przeładujesz osobno automatyzacje, skrypty, sceny czy encje szablonów.

Urządzenie lub usługa niedostępne w chwili startu

To typowa przyczyna statusu „Retrying setup”. Urządzenie dostało nowy adres IP po restarcie routera, broker MQTT (np. dodatek Mosquitto) startuje wolniej, a serwer NAS albo kamera jeszcze się nie uruchomiły. Integracja ponawia próby sama, więc często wystarczy poczekać. Na stałe pomaga rezerwacja adresu IP w DHCP routera dla każdego urządzenia, z którym HA łączy się po sieci. Jeśli adres już się zmienił, część integracji ma w menu opcję ponownej konfiguracji. W pozostałych trzeba usunąć wpis i dodać go od nowa.

Wygasłe hasło lub token

Po zmianie hasła do konta producenta albo wygaśnięciu tokenu integracja nie przejdzie konfiguracji. Nowsze integracje zgłaszają to same jako „wymagane ponowne uwierzytelnienie” w Naprawach lub na karcie integracji. Wystarczy kliknąć i zalogować się ponownie, bez usuwania urządzeń i ich encji.

Integracja niestandardowa po aktualizacji HA

Integracje z HACS nie przechodzą testów razem z wydaniem Home Assistant. Ostrzeżenie „custom integration … has not been tested by Home Assistant” jest standardowe i samo w sobie nie oznacza problemu. Błędy pojawiają się wtedy, gdy nowa wersja HA zmienia lub usuwa funkcję, z której korzysta integracja. W logach widać wtedy najczęściej ImportError albo AttributeError przy jej nazwie. Sprawdź w HACS, czy jest nowsza wersja, i zajrzyj do zgłoszeń w repozytorium na GitHubie. Jeśli poprawki jeszcze nie ma, zostają dwie drogi: przywrócić kopię sprzed aktualizacji albo poczekać. Więcej o problemach po aktualizacji przeczytasz w artykule Home Assistant po aktualizacji nie działa — jak to naprawić.

Koordynator Zigbee lub inne urządzenie USB

Ścieżka typu /dev/ttyUSB0 lub /dev/ttyACM0 potrafi się zmienić po restarcie albo po podłączeniu drugiego urządzenia USB. ZHA czy Zigbee2MQTT nie znajdą wtedy koordynatora. W konfiguracji używaj stałej ścieżki /dev/serial/by-id/…, którą pokazuje karta sprzętu w Ustawienia → System → Sprzęt lub polecenie ls -l /dev/serial/by-id/. W Dockerze sprawdź też, czy po odtworzeniu kontenera urządzenie dalej jest przekazane w sekcji devices. Problemy z samym koordynatorem opisuje artykuł koordynator Zigbee nie widzi urządzenia.

Pełny dysk lub uszkodzona baza danych

Brak miejsca na dysku daje objawy, które trudno powiązać z przyczyną: część integracji nie zapisuje stanu, historia się urywa, a start trwa długo. Sprawdź zajętość w Ustawienia → System → Pamięć albo poleceniem df -h. Najczęściej rośnie baza historii home-assistant_v2.db. Zmniejszy ją krótszy okres przechowywania (purge_keep_days w sekcji recorder) i wykluczenie encji, które często zmieniają stan. Jeśli HA wykryje uszkodzoną bazę SQLite, odkłada ją pod nazwą z końcówką .corrupt i zakłada nową. Tracisz wtedy historię, ale integracje nadal działają.

Usunąć i dodać ponownie czy przywrócić kopię

Usunięcie integracji i dodanie jej od nowa to szybki sposób na uszkodzony wpis, ale ma swój koszt. Mogą zmienić się identyfikatory encji, a automatyzacje i dashboardy, które z nich korzystały, trzeba poprawić ręcznie. Zrób to dopiero wtedy, gdy logi wskazują na sam wpis integracji, a ponowne uwierzytelnienie i opcja ponownej konfiguracji nie pomogły.

Gdy problem pojawił się zaraz po aktualizacji albo dotyczy wielu integracji naraz, pewniejsza jest kopia zapasowa z Ustawienia → System → Kopie zapasowe. Przywrócenie pełnej kopii odtwarza konfigurację razem z wersją Home Assistant, więc nie powstają niezgodności między plikami a kodem. Nie edytuj ręcznie plików w katalogu .storage (np. core.config_entries) przy działającym HA. Usunięcie tego katalogu oznacza utratę konfiguracji wszystkich integracji dodanych przez interfejs, a nie tylko tej jednej. Jak ustawić automatyczne kopie, opisuje artykuł o backupie Home Assistant.

Najczęściej zadawane pytania (FAQ)

Czy po każdym restarcie trzeba ponownie dodawać integracje? Nie. Integracje dodane przez interfejs są zapisane w konfiguracji i wracają same. Jeśli znikają za każdym razem, sprawdź logi z momentu startu, wolne miejsce na dysku i czy katalog konfiguracji (w Dockerze wolumen /config) jest zapisywany trwale.

Integracja działa, ale urządzenia są „unavailable”. Dlaczego? Integracja połączyła się z chmurą lub mostkiem, ale nie z samymi urządzeniami. Najczęściej winny jest zmieniony adres IP, wyłączone urządzenie albo słaby zasięg w sieci Zigbee lub Wi-Fi. Zarezerwuj adresy w routerze i sprawdź, czy urządzenie odpowiada w aplikacji producenta.

Logi nie pokazują żadnego błędu. Co dalej? Włącz rejestrowanie debugowania dla tej integracji i przeładuj ją. Domyślny poziom logów często ukrywa przyczynę. Jeśli także wtedy nic nie widać, zrestartuj HA w trybie awaryjnym, żeby wykluczyć konflikt z integracją niestandardową.

Czy przeładowanie integracji wystarczy zamiast restartu? Często tak. Opcja „Przeładuj” w menu integracji uruchamia ponownie tylko ją, bez zatrzymywania całego systemu. Pełny restart jest potrzebny po zmianach w configuration.yaml dotyczących integracji, które nie obsługują przeładowania, i po instalacji lub aktualizacji integracji z HACS.