Skip to content

Troubleshooting EN

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

Troubleshooting

Sprache: English · Deutsch

Common issues during setup and operation, with diagnostic steps and fixes.

Setup Issues

"Invalid credentials" during setup

  • Double-check that you are entering the Application Key and Application Secret from the Husqvarna Developer Portal — not your Husqvarna account username/password.
  • Verify that your Gardena/Husqvarna account is linked properly.
  • After rotating credentials, allow a few minutes for the Husqvarna backend to propagate the new key.

"API access denied" during setup

  • Ensure the correct API is connected to your application in the Husqvarna Developer Portal:
    • For Gardena devices: enable the Gardena Smart System API.
    • For Automower: enable the Automower Connect API.
  • Both APIs can be enabled on the same application.

"Automower Connect API is not connected" during setup

Runtime Issues

Devices show as unavailable

  • Gardena devices: The device may be out of RF range of the Gardena Smart Gateway. Check that the gateway is powered on and connected to your network.
  • Automower: The mower may be out of cellular/Wi-Fi range. Check connectivity in the Husqvarna Automower app.
  • Battery-powered devices may go offline when the battery is depleted.

"Real-time connection lost" repair issue

This indicates the WebSocket connection to the Husqvarna cloud has failed. The integration continues to work via polling, but updates will be delayed.

  • A watchdog timer monitors the WebSocket connection and detects silent failures within 5 minutes. When triggered, it forces a reconnect and an immediate data refresh.
  • The integration also automatically reconnects with graduated backoff (60 s → 5 min → 15 min, 3 attempts). After 3 consecutive failures the circuit breaker activates a 15-minute cooldown (30 min after 5 failures, 60 min after 7+). REST polling continues uninterrupted during the cooldown. No manual action required.
  • The repair issue resolves itself once the connection is restored.
  • If it persists, check your Home Assistant host's internet connection or the Husqvarna service status for outages.

Repeated "WebSocket connection lost" warnings every ~6 minutes

If your log shows a regular pattern of Gardena WebSocket watchdog: no message received for ~360s, forcing disconnect and reconnect followed by reconnect attempts (and sometimes HTTP 410 on the next handshake), and you are on a release older than 1.12.9, this is the over-aggressive watchdog killing healthy connections (see issue #18). The pattern depends on how often your devices change state — quiet gardens (no active mowing or watering) trigger it most. Update to 1.12.9 or newer — the watchdog timeout was raised from 5 to 30 minutes, the duplicate log lines were collapsed, and transient drops only escalate to WARN once they become persistent.

Device state appears frozen or stale for up to ~2 hours (fixed in v2.0.5)

If device state stops updating for roughly 2 hours and then suddenly catches up, you are likely hitting Husqvarna's server-side 2-hour maximum WebSocket session duration. The server enforces this limit for load-balancing purposes by sending a graceful CLOSE frame; the aiogardenasmart library exits its receive loop normally on such a close (no exception), so the integration was never notified of the disconnect — _ws_connected stayed True and the coordinator continued silently running on stale data until the 4-hour watchdog eventually fired.

This is resolved in v2.0.5. A proactive reconnect timer (WS_MAX_SESSION_SECONDS = 6900 s, i.e. 1 h 55 min — 5 minutes before the server limit) is now scheduled whenever a WebSocket session is established. The timer triggers a clean disconnect and reconnect before the server closes the connection. If you see this issue, update to v2.0.5 or newer.

"Husqvarna Application blocked" repair issue

This is a more severe variant of the WebSocket connection issue: the signed WebSocket URLs are being rejected by the Husqvarna/AWS gateway with HTTP 410/403/429, or REST polls have been hitting 429 for ≥10 attempts in a 24-hour window with no successful poll in between. Both patterns typically mean the application has been blocked server-side (e.g. quota exhausted, key revoked, or fraud detection).

  1. Open the Husqvarna Developer Portal.
  2. Create a new Application (or rotate the existing one) and note the new Application Key and Secret.
  3. Enable the same APIs as before (Gardena Smart System API, Automower Connect API).
  4. In Home Assistant, open the integration entry and Reconfigure with the new credentials.

The repair issue clears automatically on the next successful WebSocket connect + device update, or after several consecutive successful REST polls. Reconfiguring with a new Client ID also wipes the persisted block state, so the new key starts from a clean slate.

Tip: If you saw this issue clear and reappear repeatedly in older releases, that was the in-memory kill-switch being reset on every config-entry setup retry. Since 1.12.8 the kill-switch state is persisted to disk and survives both HA restarts and setup retries — so a fresh coordinator immediately respects an active 1-hour cooldown without burning another quota call to confirm the block.

Commands fail with "Failed to send command" or "Gardena cloud did not respond in time"

The integration surfaces two distinct command-error translations, and which one you see matters:

  • command_failed — a deterministic rejection from the Husqvarna backend (4xx, library error, device-unavailable). Retrying will not help; check device availability in the Gardena/Automower app and the HA logs for the underlying message.
  • command_timeout — the Husqvarna cloud gateway returned 502/503/504 or the request timed out client-side. The command may or may not have reached the device. Since v1.12.15 the integration automatically retries up to 3 times, polling the cached WebSocket-pushed state for up to 15 s between attempts before giving up — so seeing this error means all 3 attempts failed (≈45 s of trying). At that point it is almost always a real Husqvarna-backend outage; check Husqvarna service status before opening an issue.
  • Check the Home Assistant logs for details (filter by gardena_smart_system). The retry path logs attempt N/3 timed out and target state not yet observed, retrying between attempts.

Scheduled mower never starts (recurring command_timeout at the top of the hour)

If a Home Assistant automation / scheduler fires lawn_mower.start_mowing at e.g. *:00 and the mower never moves, but starting it manually via the Gardena app a minute later works fine, you are most likely hitting Husqvarna's top-of-the-hour gateway congestion (issue #27). Many users have schedules at full-hour boundaries, the cloud gateway briefly returns HTTP 504 (Endpoint request timed out), and on older releases that one failed call was the end of it.

  • Update to 1.12.15 or newer. Every command is now retried up to 3 times automatically (~15 s WebSocket-state confirmation between attempts), without any options-flow toggle. Mower commands are idempotent (START_DONT_OVERRIDE on an already-mowing mower is a no-op), so the retry cannot cause double-execution. Worst-case wall time on a real outage is ~45 s.
  • If the issue persists on 1.12.15+, the new log line attempt 1/3 timed out and target state not yet observed, retrying will show up between attempts — share those lines plus the final command_timeout log in the bug report. That means the Husqvarna cloud was down for the full retry window, which is outside what the integration can fix.
  • As a side mitigation, move scheduled commands a few minutes off the full hour (e.g. *:07 instead of *:00) to dodge the worst gateway congestion.

"Commands are being sent too quickly"

  • The integration uses a token-bucket throttle (10 commands, refilling at 1 per 5 s). Short bursts (e.g. opening several valves at once) are allowed; the warning only appears once an automation has fired 10+ commands in quick succession.
  • If you see this in automations, add a delay step between consecutive service calls, or spread them out further.

"Rate limited" in logs

  • The Husqvarna API has temporarily blocked your API key due to too many requests.
  • The integration automatically backs off and recovers on its own (5 min → 10 → 20 → 40 → 60 min).
  • If this happens frequently, review your automations and HA restart habits. See API Rate Limits for tips.

API budget below 5 % — auto-stop active

When the monthly API budget drops below 5 % remaining, the integration automatically pauses all REST polls, WebSocket reconnects, and user commands until the next calendar month. Commands return a translated error (api_budget_exhausted).

To restore service before month-end:

  1. Create a new Husqvarna Application in the Developer Portal.
  2. Reconfigure the integration with the new credentials. The budget counter is reset on Client-ID change, restoring the full quota.

Diagnostic Tools

  • Hub diagnostic sensors — every config entry exposes Device count, Polling interval, API requests this month, API budget remaining for visibility into the integration's health.

  • HA diagnostics download — go to the integration entry → three-dot menu → Download diagnostics to get a JSON dump (with sensitive data redacted: credentials, serial numbers, GPS coordinates, device names).

  • Log filter — set a custom log level to see what the integration is doing:

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

Reporting a Bug

If the steps above don't resolve the issue:

  1. Collect HA logs (Settings → System → Logs) with the integration's debug logging enabled.
  2. Download the diagnostics JSON from the integration entry.
  3. Open an issue at the GitHub issue tracker with logs, diagnostics, and a description of what you expected vs. what happened.

See also: API Rate Limits · Limitations

Home

English

Deutsch

Repo · Issues · Releases

Clone this wiki locally