Skip to content

Troubleshooting DE

Jump to bottom
Kay Löhmann edited this page May 30, 2026 · 5 revisions

Fehlerbehebung

Sprache: Deutsch · English

Häufige Probleme bei Einrichtung und Betrieb mit Diagnoseschritten und Lösungen.

Probleme bei der Einrichtung

„Ungültige Zugangsdaten" beim Einrichten

  • Sicherstellen, dass Application Key und Application Secret aus dem Husqvarna Developer Portal eingetragen werden — nicht Husqvarna-Benutzername und -Passwort.
  • Prüfen, ob das Gardena-/Husqvarna-Konto korrekt verknüpft ist.
  • Nach dem Rotieren der Zugangsdaten ein paar Minuten warten, bis das Husqvarna-Backend den neuen Schlüssel propagiert hat.

„API-Zugriff verweigert" beim Einrichten

  • Prüfen, ob die richtige API in der Application im Husqvarna Developer Portal verbunden ist:
    • Für Gardena-Geräte: Gardena Smart System API aktivieren.
    • Für Automower: Automower Connect API aktivieren.
  • Beide APIs können in derselben Application aktiv sein.

„Automower Connect API ist nicht verbunden" beim Einrichten

Probleme im Betrieb

Geräte sind nicht verfügbar

  • Gardena-Geräte: Möglicherweise ausserhalb der Funkreichweite des Gardena Smart Gateway. Prüfen, ob das Gateway eingeschaltet und mit dem Netzwerk verbunden ist.
  • Automower: Möglicherweise ausserhalb der Mobilfunk-/WLAN-Reichweite. Verbindung in der Husqvarna-Automower-App prüfen.
  • Batteriebetriebene Geräte gehen offline, sobald die Batterie leer ist.

Repair-Issue „Echtzeitverbindung verloren"

Zeigt an, dass die WebSocket-Verbindung zur Husqvarna-Cloud fehlgeschlagen ist. Die Integration arbeitet weiterhin via Polling, Updates kommen aber verzögert.

  • Ein Watchdog-Timer überwacht die WebSocket und erkennt stille Ausfälle innerhalb von 5 Minuten. Bei Auslösung wird ein Reconnect und ein sofortiges Daten-Refresh erzwungen.
  • Die Integration verbindet zudem automatisch neu mit graduiertem Backoff (60 s → 5 min → 15 min, 3 Versuche). Nach 3 aufeinanderfolgenden Fehlversuchen aktiviert der Circuit Breaker eine 15-Minuten-Cooldown (30 min nach 5 Fehlern, 60 min nach 7+). REST-Polling läuft während der Cooldown ungestört weiter. Kein manueller Eingriff nötig.
  • Die Repair-Issue löst sich automatisch, sobald die Verbindung wiederhergestellt ist.
  • Bleibt sie bestehen: Internetverbindung des Home-Assistant-Hosts und Husqvarna-Servicestatus auf Ausfälle prüfen.

Wiederkehrende „WebSocket connection lost"-Warnungen alle ~6 Minuten

Wenn das Log ein regelmäßiges Muster aus Gardena WebSocket watchdog: no message received for ~360s, forcing disconnect and reconnect mit anschließenden Reconnect-Versuchen zeigt (und manchmal HTTP 410 beim nächsten Handshake), und du auf einer Version vor 1.12.9 bist, ist das der zu aggressive Watchdog, der gesunde Verbindungen killt (siehe Issue #18). Wie oft das Muster auftritt, hängt davon ab, wie aktiv deine Geräte sind — ruhige Gärten (kein laufender Mäher, keine Bewässerung) lösen es am häufigsten aus. Auf 1.12.9 oder neuer aktualisieren — der Watchdog-Timeout wurde von 5 auf 30 Minuten angehoben, die doppelten Log-Zeilen zusammengefasst, und transiente Verbindungsabbrüche werden erst zu WARN, wenn sie persistent sind.

Gerätezustand scheint bis zu ~2 Stunden eingefroren (behoben in v2.0.5)

Wenn Gerätezustände für etwa 2 Stunden nicht aktualisiert werden und dann plötzlich nachholen, liegt das wahrscheinlich an Husqvarnas serverseitigem 2-Stunden-Maximum für WebSocket-Sitzungen. Der Server erzwingt dieses Limit aus Lastausgleichsgründen durch einen regulären CLOSE-Frame; die aiogardenasmart-Bibliothek beendet ihre Empfangsschleife dabei normal (keine Exception), sodass die Integration nie über den Verbindungsabbruch informiert wurde — _ws_connected blieb True und der Coordinator lief still auf veralteten Daten, bis nach 4 Stunden der Watchdog anschlug.

Behoben in v2.0.5. Es wird jetzt ein proaktiver Reconnect-Timer (WS_MAX_SESSION_SECONDS = 6900 s, also 1 Std. 55 Min. — 5 Minuten vor dem Serverlimit) gesetzt, sobald eine WebSocket-Sitzung aufgebaut wird. Der Timer löst ein sauberes Trennen und Wiederverbinden aus, bevor der Server die Verbindung schließt. Bei diesem Problem: Auf v2.0.5 oder neuer aktualisieren.

Repair-Issue „Husqvarna-Application gesperrt"

Eine schwerere Variante der WebSocket-Verbindungsproblematik: Die signierten WebSocket-URLs werden vom Husqvarna-/AWS-Gateway mit HTTP 410/403/429 abgelehnt, oder REST-Polls schlagen seit ≥10 Versuchen innerhalb von 24 Stunden mit 429 fehl, ohne dass dazwischen ein erfolgreicher Poll lag. Beide Muster bedeuten typischerweise, dass die Application serverseitig gesperrt wurde (z. B. Kontingent erschöpft, Schlüssel widerrufen oder Betrugserkennung ausgelöst).

  1. Das Husqvarna Developer Portal öffnen.
  2. Eine neue Application anlegen (oder die bestehende rotieren) und den neuen Application Key und das Secret notieren.
  3. Dieselben APIs wie vorher aktivieren (Gardena Smart System API, Automower Connect API).
  4. In Home Assistant den Integrationseintrag öffnen und mit den neuen Zugangsdaten Neu konfigurieren.

Die Repair-Issue verschwindet automatisch beim nächsten erfolgreichen WebSocket-Connect + Geräte-Update oder nach mehreren erfolgreichen REST-Polls in Folge. Das Neukonfigurieren mit einer neuen Client-ID setzt zusätzlich den persistierten Block-Zustand zurück, damit der neue Schlüssel sauber startet.

Hinweis: Wenn diese Issue in älteren Versionen wiederholt verschwand und sofort wieder auftauchte, lag es am In-Memory-Kill-Switch, der bei jedem Setup-Retry des Config-Entries zurückgesetzt wurde. Seit 1.12.8 wird der Kill-Switch-Zustand auf Disk persistiert und überlebt sowohl HA-Neustarts als auch Setup-Retries — ein frischer Coordinator respektiert eine aktive 1-stündige Cooldown sofort, ohne erneut Quota zu verbrennen, um den Block zu bestätigen.

Befehle schlagen mit „Befehl konnte nicht gesendet werden" oder „Die Gardena-Cloud hat nicht rechtzeitig geantwortet" fehl

Die Integration liefert zwei unterschiedliche Befehls-Fehlertexte, und der Unterschied ist wichtig:

  • command_failed — eine deterministische Ablehnung vom Husqvarna-Backend (4xx, Bibliotheksfehler, Gerät nicht verfügbar). Ein Wiederholen hilft nicht; Geräteverfügbarkeit in der Gardena-/Automower-App prüfen und die HA-Logs nach der zugrundeliegenden Meldung durchsehen.
  • command_timeout — das Husqvarna-Cloud-Gateway hat 502/503/504 geliefert oder die Anfrage ist client-seitig in einen Timeout gelaufen. Der Befehl kann beim Gerät angekommen sein oder eben nicht. Seit v1.12.15 wiederholt die Integration jeden Befehl automatisch bis zu 3-mal, prüft dazwischen für je 15 s den per WebSocket gepushten Gerätezustand, und gibt erst danach auf — d. h. dieser Fehler bedeutet, dass alle 3 Versuche fehlgeschlagen sind (≈45 s versucht). An dem Punkt liegt fast immer ein echter Husqvarna-Backend-Ausfall vor; den Husqvarna-Servicestatus prüfen, bevor ein Issue eröffnet wird.
  • Die Home-Assistant-Logs nach Details durchsuchen (Filter: gardena_smart_system). Der Retry-Pfad loggt zwischen den Versuchen attempt N/3 timed out and target state not yet observed, retrying.

Geplanter Mäher startet nie (wiederkehrender command_timeout zur vollen Stunde)

Wenn eine Home-Assistant-Automatisierung / ein Scheduler lawn_mower.start_mowing z. B. um *:00 auslöst und der Mäher nie losfährt, ein manueller Start in der Gardena-App eine Minute später aber problemlos funktioniert, ist das mit hoher Wahrscheinlichkeit Husqvarnas Gateway-Überlastung zur vollen Stunde (Issue #27). Viele Anwender haben Schedules zur vollen Stunde, das Cloud-Gateway antwortet kurzzeitig mit HTTP 504 (Endpoint request timed out), und in älteren Versionen war dieser eine fehlgeschlagene Aufruf das Ende.

  • Auf 1.12.15 oder neuer aktualisieren. Jeder Befehl wird jetzt automatisch bis zu 3-mal wiederholt (~15 s WebSocket-Zustandsabgleich zwischen Versuchen), ohne dass eine Option in den Einstellungen gesetzt werden müsste. Mäher-Befehle sind idempotent (START_DONT_OVERRIDE auf einen bereits mähenden Mäher ist ein No-Op), daher kann das Wiederholen keine Doppel-Ausführung verursachen. Worst-Case-Laufzeit bei echtem Ausfall ≈45 s.
  • Tritt das Problem auf 1.12.15+ weiter auf, erscheint zwischen den Versuchen die neue Log-Zeile attempt 1/3 timed out and target state not yet observed, retrying — diese Zeilen plus die abschließende command_timeout-Meldung im Bug-Report mitschicken. Das bedeutet, dass die Husqvarna-Cloud das gesamte Retry-Fenster über down war, was außerhalb dessen liegt, was die Integration ausgleichen kann.
  • Als zusätzliche Maßnahme: Schedule-Befehle ein paar Minuten neben die volle Stunde legen (z. B. *:07 statt *:00), um der schlimmsten Gateway-Überlastung auszuweichen.

„Befehle werden zu schnell gesendet"

  • Die Integration nutzt einen Token-Bucket (10 Befehle, Refill 1 pro 5 s). Kurze Bursts (z. B. mehrere Ventile gleichzeitig öffnen) sind erlaubt; die Warnung erscheint erst, wenn eine Automatisierung 10+ Befehle in schneller Folge absetzt.
  • Tritt dies in Automatisierungen auf, einen delay-Schritt zwischen Service-Aufrufe einbauen oder zeitlich entzerren.

„Rate limited" im Log

  • Die Husqvarna-API hat den API-Schlüssel wegen zu vieler Anfragen vorübergehend geblockt.
  • Die Integration backt automatisch zurück und erholt sich selbst (5 min → 10 → 20 → 40 → 60 min).
  • Tritt das häufig auf, Automatisierungen und HA-Neustart-Verhalten überprüfen. Tipps siehe API-Rate-Limits.

API-Budget unter 5 % — Auto-Stop aktiv

Sinkt das Monatsbudget unter 5 % Restwert, pausiert die Integration automatisch alle REST-Polls, WebSocket-Reconnects und Benutzerbefehle bis zum nächsten Kalendermonat. Befehle geben eine übersetzte Fehlermeldung zurück (api_budget_exhausted).

Um den Betrieb vor dem Monatswechsel wiederherzustellen:

  1. Eine neue Husqvarna-Application im Developer Portal anlegen.
  2. Die Integration mit den neuen Zugangsdaten neu konfigurieren. Der Budget-Zähler wird beim Wechsel der Client ID zurückgesetzt und das volle Kontingent steht wieder zur Verfügung.

Diagnose-Werkzeuge

  • Hub-Diagnose-Sensoren — jeder Konfigurationseintrag stellt Geräteanzahl, Polling-Intervall, API-Anfragen diesen Monat, Verbleibendes API-Budget bereit, um die Integration zu beobachten.

  • HA-Diagnose-Download — Integrationseintrag → Drei-Punkte-Menü → Diagnose herunterladen liefert einen JSON-Dump (mit redigierten sensiblen Daten: Zugangsdaten, Seriennummern, GPS-Koordinaten, Gerätenamen).

  • Log-Level erhöhen — um zu sehen, was die Integration intern tut:

    logger:
  logs:
    custom_components.gardena_smart_system: debug
    aiogardenasmart: debug

Bug melden

Bringen die obigen Schritte keine Lösung:

  1. HA-Logs sammeln (Einstellungen → System → Protokoll) mit aktiviertem Debug-Logging.
  2. Diagnose-JSON aus dem Integrationseintrag herunterladen.
  3. Im GitHub-Issue-Tracker ein Issue eröffnen — mit Logs, Diagnose und einer Beschreibung von Soll/Ist.

Siehe auch: API-Rate-Limits · Einschränkungen

Home

English

Deutsch

Repo · Issues · Releases

Clone this wiki locally