Skip to content

Connection Issues

Problems connecting Hanergy to Home Assistant, or entity values not appearing correctly.

"HA Connection: Disconnected" on the Dashboard

The dashboard shows the connection status to Home Assistant. If it reads "Disconnected", work through the following:

1. Verify the add-on configuration

For HA add-on installations, the add-on manifest must include homeassistant_api: true. Without this, the Supervisor does not inject the authentication token into the container, and Hanergy cannot connect to Home Assistant.

Note

This is configured in the add-on manifest, not by the user. If you installed from the official repository, this should already be set. If the connection fails immediately after installation, reinstall the add-on to ensure the manifest is correct.

2. Check the add-on logs

Go to Settings > Add-ons > Hanergy > Log. Look for messages from the WebSocket manager. A failed initial connection logs the error and begins retrying.

3. Understand reconnection behavior

Hanergy reconnects automatically with exponential backoff:

  • First retry: 1 second
  • Subsequent retries: doubling each time, capping at 30 seconds

A brief "Disconnected" indicator after a Home Assistant restart is normal and self-resolves within seconds.

4. Docker installations

For standalone Docker deployments, verify the environment variables:

  • HA_URL must be the full URL to your Home Assistant instance (e.g., http://192.168.1.100:8123)
  • HA_TOKEN must be a valid Long-Lived Access Token (create one in your HA profile page)

Warning

If neither HA_URL/HA_TOKEN nor SUPERVISOR_TOKEN is set, Hanergy enters dev mode and intentionally skips the connection. The log will show "dev mode: skipping websocket and engine". This is not a bug -- it means the connection credentials are missing.

Entity Values Showing as 0

Entity state is populated by the WebSocket subscription to Home Assistant. Until at least one state-change event arrives for an entity, its cached value is zero.

Checklist:

  • Verify entity IDs match exactly. Go to Settings > Energy Entities in Hanergy and compare each entity ID with what Home Assistant reports. Entity IDs are case-sensitive.
  • Confirm entities exist in HA. Open HA Developer Tools > States and search for each entity ID. If the entity does not appear, the sensor integration may not be loaded.
  • Wait one evaluation cycle. After a fresh start, allow at least one evaluation cycle (default: 10 seconds) for the cache to populate from incoming state events.
  • Check for "unavailable" state. If an entity exists in HA but reports unavailable, the underlying device or integration has lost contact. Resolve the issue in HA first.

WebSocket Reconnection

The WebSocket connection between Hanergy and Home Assistant may drop temporarily due to:

  • Home Assistant restarting
  • Network interruption
  • Supervisor maintenance

Hanergy handles this automatically. During a disconnection:

  • The engine pauses evaluation (no decisions are made with stale data).
  • The WebSocket manager retries with exponential backoff.
  • Once reconnected, entity states are refreshed and the engine resumes.

No user action is required. If the connection does not recover within a few minutes, check that Home Assistant itself is running and accessible.