Home Assistant Troubleshooting

Home Assistant startet nicht: Checkliste

1. Strom?
2. Speicher?
3. Netzwerk?
4. Config?
5. Add-ons?
6. Backup?

Hinweis: Installiere immer das SSH Add-on bevor du es brauchst! Im Notfall ist SSH oft der einzige Weg, auf HA zuzugreifen, wenn die Web-UI nicht mehr funktioniert.

Notfall-Befehle über SSH

1# SSH-Befehle für Notfälle
2# Home Assistant Core neu starten
3ha core restart
4
5# Home Assistant Core stoppen und starten
6ha core stop
7ha core start
8
9# Alle Add-ons stoppen
10ha addons stop [addon_slug]
11
12# Logs anzeigen
13ha core logs
14ha supervisor logs
15
16# Backup erstellen
17ha backups new --name "notfall-backup"
18
19# System-Info anzeigen
20ha info
21ha os info
22
23# Konfiguration prüfen
24ha core check
25
26# Datenbank zurücksetzen (Vorsicht!)
27# Stoppt HA, löscht home-assistant_v2.db
28ha core stop
29rm /config/home-assistant_v2.db
30ha core start
31# ACHTUNG: Verliert alle Verlaufsdaten!

Notfall: Auth-Datei zurücksetzen

Wenn du dich ausgesperrt hast und weder Login noch 2FA funktionieren:

1# Authentifizierung zurücksetzen (SSH)
2# Schritt 1: HA stoppen
3ha core stop
4
5# Schritt 2: Auth-Provider zurücksetzen
6# ACHTUNG: Löscht ALLE Benutzerkonten!
7rm /config/.storage/auth
8rm /config/.storage/auth_provider.homeassistant
9
10# Schritt 3: HA starten
11ha core start
12
13# Schritt 4: Onboarding wird erneut gestartet
14# Du erstellst ein neues Admin-Konto
15# Alle Automationen und Geräte bleiben erhalten

Hinweis: Das Zurücksetzen der Authentifizierung löscht alle Benutzerkonten. Nutze es nur, wenn du komplett ausgesperrt bist. Danach sofort neues Konto erstellen und 2FA einrichten!

Logs lesen und verstehen

Logs sind dein wichtigstes Debugging-Tool. Du findest sie unter Einstellungen → System → Protokolle.

Debug-Logging für eine Integration aktivieren

1# Debug-Logging (configuration.yaml)
2logger:
3  default: warning               # Standard-Level
4  logs:
5    homeassistant.components.shelly: debug    # Shelly debuggen
6    homeassistant.components.zha: debug       # ZHA debuggen
7    homeassistant.components.mqtt: debug      # MQTT debuggen
8    custom_components.hacs: debug             # HACS debuggen
9    aiohttp.access: warning                   # HTTP-Noise reduzieren
10
11# TIPP: Debug-Logging erzeugt VIEL Output!
12# Aktiviere es nur temporär und schalte es danach wieder ab.
13# Dauerhaftes Debug-Logging füllt die Datenbank schnell.

Logs effektiv durchsuchen

1# Nützliche Log-Strategien
2# 1. Im Browser: Einstellungen > System > Protokolle
3#    → Suchfeld nutzen (z.B. "shelly" oder "error")
4
5# 2. Per SSH: Logs in Echtzeit verfolgen
6ha core logs --follow
7
8# 3. Nur Fehler anzeigen
9ha core logs | grep -i "error"
10
11# 4. Logs einer bestimmten Integration
12ha core logs | grep -i "zha"
13
14# 5. Automation-Traces nutzen (beste Methode!):
15# Einstellungen > Automationen > [Automation] > Traces
16# Zeigt jeden einzelnen Schritt der letzten 20 Ausführungen
17# mit Timing, Variablenwerten und Fehlern

Hinweis: Im Protokoll-Bereich kannst du nach Integrationsnamen filtern. Tippe z.B. „shelly" in die Suchleiste, um nur Shelly-bezogene Meldungen zu sehen. Für Automations-Debugging sind Traces (Ablaufverfolgung) oft besser als Logs!

Automationen debuggen

Wenn eine Automation nicht funktioniert, gehe systematisch vor:

1. Trace prüfen: Einstellungen → Automationen → Automation wählen → Traces. Zeigt jeden Schritt der letzten Ausführung.
2. Manuell auslösen: Klicke auf Ausführen um die Automation ohne Trigger zu testen. Überprüfe ob die Actions funktionieren.
3. Trigger prüfen: Entwicklerwerkzeuge → Zustände: Prüfe ob die Entity den erwarteten Wert hat.
4. Conditions prüfen: Entwicklerwerkzeuge → Template: Teste die Condition als Template. Ergebnis true oder false?
5. Logs prüfen: Einstellungen → System → Protokolle. Filter nach dem Automationsnamen.

Häufige Automation-Fehler und Lösungen

1# Debug-Automation: Alle Trigger-Daten loggen
2automation:
3  - alias: "Debug: Trigger-Daten anzeigen"
4    trigger:
5      - platform: state
6        entity_id: binary_sensor.haustuer
7    action:
8      # Schritt 1: In Notification anzeigen
9      - service: persistent_notification.create
10        data:
11          title: "Debug Trigger"
12          message: >
13            Entity: {{ trigger.entity_id }}
14            Von: {{ trigger.from_state.state }}
15            Nach: {{ trigger.to_state.state }}
16            Zeit: {{ trigger.to_state.last_changed }}
17
18      # Schritt 2: In Logs schreiben
19      - service: system_log.write
20        data:
21          message: >
22            TRIGGER: {{ trigger.entity_id }}
23            changed from {{ trigger.from_state.state }}
24            to {{ trigger.to_state.state }}
25          level: warning

Backup: Dein Sicherheitsnetz

Backup erstellen

1. Sicherungen öffnen: Einstellungen → System → Sicherungen
2. Sicherung erstellen: Klicke auf Sicherung erstellen, Vollständig oder Teilweise
3. Warten: Je nach Größe dauert das Backup 1–10 Minuten
4. Herunterladen! Lade das Backup herunter und speichere es extern (NAS, Cloud, USB)

Hinweis: Ein Backup auf der gleichen SD-Karte/SSD nützt nichts, wenn das Speichermedium stirbt! Lade Backups immer herunter oder automatisiere die Übertragung auf ein NAS/Cloud-Speicher.

Was ist im Backup enthalten?

Automatische Backups

1# Automation: Tägliches Backup mit Benachrichtigung
2automation:
3  - alias: "Tägliches Backup um 3 Uhr"
4    trigger:
5      - platform: time
6        at: "03:00:00"
7    action:
8      - service: backup.create
9        data:
10          name: "auto_{{ now().strftime('%Y-%m-%d') }}"
11      - delay: "00:10:00"      # Warten bis Backup fertig
12      - service: notify.mobile_app_mein_handy
13        data:
14          title: "Backup erstellt"
15          message: >
16            Tägliches Backup wurde erfolgreich erstellt.
17            Datum: {{ now().strftime('%d.%m.%Y %H:%M') }}

Backup auf Google Drive (automatisch)

Das Add-on „Google Drive Backup" (HACS) erstellt automatisch Backups und lädt sie auf dein Google Drive hoch.

• Automatisch: Tägliche Backups ohne manuelles Eingreifen
• Rotation: Alte Backups werden automatisch gelöscht (z.B. nur letzte 7 behalten)
• Verschlüsselt: Optional Passwort-geschützte Backups
• Benachrichtigung: Push-Notification wenn Backup fehlschlägt

Updates sicher durchführen

1. Backup erstellen: Immer vor einem Update eine vollständige Sicherung machen!
2. Release Notes lesen: Blog-Post auf home-assistant.io lesen, besonders die Breaking Changes
3. Update installieren: Einstellungen → System → Updates → HA Core aktualisieren
4. Logs prüfen: Nach dem Neustart die Logs auf Fehler prüfen
5. Integrationen testen: Stichprobenartig prüfen ob alle Geräte noch reagieren

Hinweis: Jedes HA-Update kann „Breaking Changes" enthalten, also Änderungen, die bestehende Konfigurationen brechen. Lies immer den Blog-Post vor dem Update! Bei großen Versionssprüngen (z.B. 2024.1 → 2024.12) besonders vorsichtig sein.

Update-Strategie

Was tun wenn ein Update schiefgeht?

1# Rollback-Strategien
2# Methode 1: Backup wiederherstellen (empfohlen)
3# Einstellungen > System > Sicherungen > Backup wählen > Wiederherstellen
4
5# Methode 2: Downgrade per SSH
6ha core update --version 2024.11.3    # Alte Version angeben
7# ACHTUNG: Downgrade kann Datenbank-Probleme verursachen!
8
9# Methode 3: Fresh Install + Backup
10# 1. HA OS neu installieren (USB-Stick flashen)
11# 2. Backup hochladen und wiederherstellen
12# 3. Alle Geräte und Automationen sind zurück
13
14# Methode 4: Nur ein Add-on zurücksetzen
15ha addons update [addon_slug] --version [alte_version]

HACS: Custom Components installieren

HACS (Home Assistant Community Store) erweitert HA um tausende Community-Integrationen und Frontend-Karten, die nicht im offiziellen Store sind. Die ausführliche Anleitung findest du im HACS-Guide.

1. HACS installieren: Über den Einrichtungsassistenten auf hacs.xyz oder manuell per SSH
2. GitHub-Token eingeben: HACS benötigt ein GitHub Personal Access Token für API-Zugriff
3. Integration hinzufügen: Einstellungen → Geräte & Dienste → + Integration → HACS
4. Komponenten installieren: HACS → Integrationen oder Frontend → Durchsuchen und installieren

Beliebte HACS-Integrationen

• Mushroom Cards: Moderne, schöne Dashboard-Karten als Ersatz für Standard-Cards
• ApexCharts Card: Fortgeschrittene Diagramme und Grafiken für das Dashboard
• Google Drive Backup: Automatische Backups auf Google Drive
• Browser Mod: Browser-Steuerung: Popups, Benachrichtigungen, Kamera
• Waste Collection: Müllabfuhr-Kalender für verschiedene Entsorger
• Battery Notes: Batterietypen und -status für alle Geräte verwalten

Hinweis: HACS-Integrationen sind nicht offiziell geprüft. Sie können Bugs enthalten oder nach HA-Updates brechen. Installiere nur populäre, aktiv gepflegte Integrationen und erstelle vorher ein Backup!

Performance optimieren

Hardware-Empfehlungen

SSD statt SD-Karte: Der wichtigste Upgrade

Die SD-Karte ist der häufigste Grund für HA-Probleme: Langsame Schreibvorgänge, Database-Locks und Verschleiß. Eine USB-SSD löst fast alle Performance-Probleme sofort. Die komplette Anleitung zur Migration findest du im Backup & Restore Guide.

Vorteile:

• 10-50x schnellere Schreibvorgänge
• Keine Database-Locked-Fehler mehr
• Längere Lebensdauer als SD-Karten
• Schnellerer Boot und Neustart
• USB-SSD ab 15 EUR (120GB)

Nachteile:

• Braucht USB-Boot-Konfiguration beim Pi
• Etwas mehr Stromverbrauch

Datenbank optimieren

1# Recorder: Datenbank schlank halten
2recorder:
3  purge_keep_days: 5             # Nur 5 Tage aufbewahren (statt 10)
4  commit_interval: 1             # Alle 1 Sekunde schreiben
5  exclude:
6    domains:
7      - media_player              # Oft unnötig
8      - weather                   # Ändert sich selten
9      - automation                # Status nicht wichtig
10      - script
11      - persistent_notification
12    entity_globs:
13      - sensor.sun_*              # Sonnenwerte
14      - sensor.*_uptime           # Uptime-Sensoren
15      - binary_sensor.*_update    # Update-Sensoren
16      - sensor.*_rssi             # WLAN-Signalstärke
17      - sensor.*_linkquality      # Zigbee LQI
18    event_types:
19      - call_service              # Sehr viele Events
20
21# Datenbank-Größe prüfen:
22# SSH: ls -lh /config/home-assistant_v2.db
23# Ziel: Unter 500 MB für gute Performance
24# Über 1 GB: Mehr excluden oder purge_keep_days reduzieren

Weitere Performance-Tipps

• SSD statt SD-Karte: Größter Performance-Gewinn! SD-Karten verschleißen schnell. USB-SSD ab 15 EUR.
• MariaDB statt SQLite: Bei 500+ Entities: MariaDB Add-on für bessere DB-Performance.
• Langsame Integrationen: Unter Reparaturen werden langsame Integrationen angezeigt.
• Unnötige Integrationen: Jede Integration verbraucht RAM und CPU. Entferne ungenutzte.
• Frontend Caching: Browser-Cache regelmäßig leeren bei Darstellungsproblemen.
• Regelmäßig neustarten: Ein wöchentlicher Neustart verhindert Memory-Leaks.

1# Automation: Wöchentlicher Neustart + System-Check
2automation:
3  - alias: "Wöchentlicher Neustart Sonntag 4 Uhr"
4    trigger:
5      - platform: time
6        at: "04:00:00"
7    condition:
8      - condition: time
9        weekday:
10          - sun
11    action:
12      # Zuerst Backup erstellen
13      - service: backup.create
14        data:
15          name: "pre_restart_{{ now().strftime('%Y-%m-%d') }}"
16      - delay: "00:05:00"
17      # Dann neustarten
18      - service: homeassistant.restart
19
20  - alias: "System-Status Check (stündlich)"
21    trigger:
22      - platform: time_pattern
23        hours: "/1"
24    condition:
25      - condition: template
26        value_template: >
27          {{ states('sensor.processor_use') | float(0) > 80
28             or states('sensor.memory_use_percent') | float(0) > 85 }}
29    action:
30      - service: notify.mobile_app_mein_handy
31        data:
32          title: "System-Warnung"
33          message: >
34            CPU: {{ states('sensor.processor_use') }}%
35            RAM: {{ states('sensor.memory_use_percent') }}%
36            DB: {{ states('sensor.home_assistant_v2_db') }}
37          data:
38            tag: system_warning

Speicher voll: So schaffst du wieder Platz

Wenn Updates fehlschlagen oder Home Assistant meldet, dass kein Backup mehr möglich ist, ist fast immer der Speicher voll. Den aktuellen Stand siehst du unter Einstellungen → System → Speicher.

Die vier üblichen Verdächtigen, in dieser Reihenfolge prüfen:

1. Die Datenbank (home-assistant_v2.db): Der größte Brocken in fast jedem System. Mit der Aktion recorder.purge räumst du sofort auf, in den Entwicklerwerkzeugen unter Aktionen ausführbar:

# Entwicklerwerkzeuge -> Aktionen
action: recorder.purge
data:
  keep_days: 7        # Nur die letzten 7 Tage behalten
  repack: true        # Gibt den Platz auch wirklich frei

Wichtig ist repack: true. Ohne diesen Schalter löscht SQLite zwar die Daten, gibt den Plattenplatz aber nicht ans System zurück. Dauerhaft hilft die recorder:-Konfiguration mit purge_keep_days und dem Ausschluss gesprächiger Entities (siehe Abschnitt Performance weiter oben).

2. Alte Backups: Unter Einstellungen → System → Sicherungen sammeln sich schnell etliche Gigabyte. Lokale Backups, die schon extern gesichert sind, kannst du bedenkenlos löschen.

3. Logdateien: Ein vergessenes Debug-Logging lässt home-assistant.log auf Gigabyte-Größe wachsen. Debug-Logging abschalten, danach schrumpft die Datei beim nächsten Neustart.

4. Medien und Schnappschüsse: Kamera-Aufnahmen und camera.snapshot-Bilder in /media und /config/www löscht niemand automatisch. Ein Blick mit dem File Editor oder Samba lohnt sich.

Tipp: Wenn gar nichts mehr geht, weil der Speicher zu 100 % voll ist: Zuerst ein altes lokales Backup löschen, das schafft sofort Luft für den recorder.purge-Lauf.

Netzwerk-Tipps

• Statische IP: Vergib HA eine feste IP im Router, das verhindert Verbindungsabbrüche nach DHCP-Lease-Erneuerung.
• mDNS/Avahi: homeassistant.local funktioniert nur mit mDNS. Im Zweifel IP nutzen.
• IoT-VLAN: Separates Netzwerk für IoT-Geräte erhöht die Sicherheit erheblich.
• WLAN-Kanal: Zigbee nutzt 2.4 GHz, wähle WLAN-Kanal 1 oder 11 für minimale Störung.
• Ethernet bevorzugen: HA immer per Kabel verbinden, nicht per WLAN. Stabiler und schneller.
• DNS-Server: Schneller DNS (1.1.1.1 oder 8.8.8.8) kann Integrationen beschleunigen.

Häufige Fehlermeldungen & Lösungen

Reparaturen-Dashboard nutzen

Seit HA 2022.7 gibt es das Reparaturen-Dashboard. Es zeigt automatisch erkannte Probleme und Verbesserungsvorschläge:

• Veraltete Konfiguration: YAML-Optionen die nicht mehr unterstützt werden
• Langsame Integrationen: Integrationen die den Start verzögern
• Migrationsbedarf: Konfigurationen die in die UI migriert werden sollten
• Sicherheitswarnungen: Unsichere Konfigurationen oder veraltete Add-ons

Hinweis: Bei komplexen Problemen: Poste deine Logs im HA Community Forum oder auf Discord. Die Community ist sehr hilfsbereit! Poste immer: HA-Version, Hardware, relevante Logs und was du bereits versucht hast.

Häufige Fragen

Warum ist mein Home Assistant Speicher voll?

Der größte Brocken ist fast immer die Datenbank home-assistant_v2.db, gefolgt von alten Backups, aufgeblähten Logdateien durch vergessenes Debug-Logging und Kamera-Schnappschüssen in /media. Den aktuellen Stand siehst du unter Einstellungen, System, Speicher. Sofort Platz schafft die Aktion recorder.purge mit repack: true, dauerhaft hilft eine schlanke Recorder-Konfiguration.

Wie kann ich Home Assistant zurücksetzen?

Das hängt davon ab, was du zurücksetzen willst. Bist du ausgesperrt, löschst du per SSH die Auth-Dateien, danach startet das Onboarding neu und alle Automationen bleiben erhalten. Für einen kompletten Neuanfang installierst du Home Assistant OS frisch und spielst optional ein Backup ein. Nur die Datenbank setzt du zurück, indem du home-assistant_v2.db löschst, das kostet aber alle Verlaufsdaten.

Was tun, wenn Home Assistant nicht startet?

Erst Ruhe bewahren: Nach einem Update kann der Start bis zu 20 Minuten dauern. Prüfe dann die IP im Router, leere den Browser-Cache und versuche es im Inkognito-Modus. Hilft das nicht, verbindest du dich per SSH und startest den Core mit ha core restart neu, die Ursache zeigt dir ha core logs.

Wie lese ich die Home Assistant Logs?

Du findest sie unter Einstellungen, System, Protokolle, mit Suchfeld zum Filtern nach Integrationsnamen. Wichtig sind vor allem Meldungen mit Level ERROR und CRITICAL, Warnungen sind oft harmlos. Für hartnäckige Fälle aktivierst du Debug-Logging für eine einzelne Integration, bei Automationen sind Traces meist aussagekräftiger als Logs.

Was tun, wenn ein Update schiefgeht?

Der sicherste Weg ist die Wiederherstellung des Backups, das du vor dem Update erstellt hast, unter Einstellungen, System, Sicherungen. Per SSH geht auch ein Downgrade mit ha core update und Versionsangabe, das kann aber Datenbank-Probleme verursachen. Im Notfall hilft eine frische Installation plus Backup-Restore.

Weiter lesen:

• Backup & Restore
• Home Assistant installieren
• YAML-Konfiguration