Startprobleme beheben und Logs analysieren

Wenn Homebridge nach einer Änderung oder einem Update nicht mehr hochfährt, hängt der Dienst meist in einer Startschleife (Boot-Loop): Er stürzt beim Initialisieren ab und das Betriebssystem startet ihn sofort neu.

Die letzten Zeilen des Logs zeigen die Ursache für den Abbruch.

Log aufrufen

Wähle deinen Zugang, um das Protokoll einzusehen:

In HomemanagerIm WebinterfacePer SSH / Terminal

1. Öffne Homemanager auf deinem iPhone oder iPad.
2. Navigiere zum Tab System und tippe auf Log.
3. Fehlermeldungen sind rot hervorgehoben.
4. Über das Teilen-Symbol oben rechts kannst du Log-Auszüge direkt kopieren oder für Supportanfragen weiterleiten.

1. Rufe die Weboberfläche im Browser auf (sofern der UI-Dienst noch erreichbar ist).
2. Öffne den Bereich Status oder das Konsolen-Symbol in der oberen Leiste.
3. Das Protokollfenster zeigt die aktuellen Meldungen an.

Verbinde dich per SSH mit deinem Host-System und lies das Protokoll mit dem Service-Manager aus:

sudo hb-service logs

Auf Linux-Systemen kannst du alternativ das systemd-Journal abfragen:

sudo journalctl -u homebridge -n 50 --no-pager

Häufige Startfehler im Überblick

1. Portkonflikte (EADDRINUSE oder Matter-Ports)

Fehlermeldung im Log:

Error: listen EADDRINUSE: address already in use :::51826

oder:

Error: Failed to allocate Matter port for child bridge.
Please specify a port manually in the _bridge.matter configuration...

• Ursache: Ein anderer Dienst belegt den HomeKit-Port (Standard: 51826), den Web-Port (8581) oder den für eine Child Bridge reservierten Matter-Port.
• Lösung:
  • Starte das System neu (sudo reboot), um verwaiste Prozesse zu beenden.
  • Falls mehrere Bridges oder Matter-Instanzen aktiv sind: Vergib in den Bridge-Einstellungen des Plugins einen festen, noch ungenutzten Port. Weitere Hintergründe findest du im Leitfaden Matter und Homebridge.

2. Syntaxfehler in der Konfiguration (SyntaxError)

Fehlermeldung im Log:

SyntaxError: Unexpected token , in JSON at position 1240

• Ursache: Ein Formatierungsfehler in der Datei config.json, meist ein überflüssiges Komma oder eine nicht geschlossene Klammer nach manueller Bearbeitung.
• Lösung:
  • Tippfehler korrigieren: Öffne die Konfiguration im Terminal (z. B. via sudo nano /var/lib/homebridge/config.json) und behebe den Syntaxfehler an der angegebenen Position.
  • Backup auf frischem System wiederherstellen: Lässt sich der Fehler nicht lokalisieren oder startet das System gar nicht mehr, setze Homebridge neu auf und stelle dein aktuellstes Backup-Archiv direkt im Einrichtungsassistenten wieder her. Alle Plugins, Einstellungen und Apple Home Kopplungen bleiben dabei vollständig erhalten.
  • Vorbeugen mit Homemanager: Konfigurationsänderungen über die Eingabemasken in Homemanager validiert die App automatisch vor dem Speichern, wodurch Syntaxfehler gar nicht erst entstehen.

3. Absturz eines Plugins beim Start

Fehlermeldung im Log:

[homebridge-plugin] Child bridge will no longer restart after failing 5 times

• Ursache: Ein Plugin stürzt während der Initialisierung ab, etwa durch ungültige Zugangsdaten oder Netzwerk-Timeouts.
• Lösung:
  • Mit Child Bridges: Läuft das Plugin als Child Bridge, stoppt Homebridge den Prozess nach fünf Fehlversuchen automatisch. Der Hauptserver bleibt online. Du kannst das Plugin in Homemanager oder im Webinterface direkt anpassen, vorübergehend deaktivieren oder dessen Konfiguration löschen. Nach der Korrektur startest du die Child Bridge wieder neu.
  • Auf der Haupt-Bridge: Wenn das Plugin auf der Haupt-Bridge läuft, reißt der Absturz den gesamten Server in eine Startschleife.
    • In Homemanager oder im Webinterface: Sofern die Oberfläche zwischen den Startversuchen noch erreichbar ist, deaktiviere das betroffene Plugin oder lösche den zugehörigen Konfigurationsblock.
    • Per Terminal (falls kein Zugriff mehr besteht): Öffne /var/lib/homebridge/config.json mit einem Editor (z. B. via sudo nano /var/lib/homebridge/config.json) und entferne den Eintrag des betroffenen Plugins aus dem Array platforms oder accessories.

4. Modulfehler nach Node.js-Updates (NODE_MODULE_VERSION)

Fehlermeldung im Log:

Error: The module '...' was compiled against a different Node.js version

• Ursache: Node.js wurde aktualisiert, während Plugins noch auf Binärmodule der Vorgängerversion zugreifen. Empfohlene Abläufe für Aktualisierungen beschreibt der Leitfaden System & Software aktualisieren.
• Lösung: Kompiliere native Module mit dem Service-Befehl neu:

  sudo hb-service rebuild

5. Zugangsdaten zur Weboberfläche vergessen

Hinweis im Log:

[Homebridge UI] Failed login attempt.
If you have forgotten your password, you can reset to the default of admin/admin...

• Lösung: Setze das Administratorkonto über das Terminal zurück:

  sudo hb-service reset-admin

  Alternativ löschst du die Datei für die Authentifizierung und startest den Dienst neu:

  sudo rm /var/lib/homebridge/auth.json && sudo hb-service restart

  Anschließend lauten Benutzername und Passwort wieder admin / admin.

Server oder Child Bridge neu starten

Nachdem du die Konfiguration korrigiert hast, startest du den Prozess neu:

• In Homemanager:
  • Den gesamten Server startest du direkt vom Dashboard aus neu.
  • Eine einzelne Child Bridge startest du wahlweise per Wischgeste (Swipe) auf dem Eintrag oder über System in den jeweiligen Bridge-Details neu.
• Im Webinterface: Klicke oben rechts auf das Power-Symbol und wähle Neu starten.
• Per Terminal: Führe sudo hb-service restart aus.