Skip to content

Troubleshooting

Jump to bottom
Marcin Gaszewski edited this page May 25, 2026 · 2 revisions

Troubleshooting

How to read the logs

All integration log messages are prefixed with sunsynk. To filter them:

Settings → System → Logs → search for sunsynk

To enable debug-level logging, add to your configuration.yaml:

logger:
  default: warning
  logs:
    custom_components.sunsynk: debug

Then restart HA and reproduce the problem. Disable debug logging again afterwards — it is verbose.

HA Repairs

The integration raises issues automatically in the HA Repair dashboard (Settings → System → Repairs):

Issue Severity Cause Clears when
Sunsynk authentication failed Error Cloud API rejected credentials Next successful authentication
Inverter {serial} is offline Warning No data returned for a serial number Next successful data fetch for that serial

These replace log hunting for the most common failure modes — check Repairs first before enabling debug logging.

Authentication problems

"Invalid credentials" on setup

  • Double-check email and password in the Sunsynk web portal
  • MFA (2-factor authentication) is not supported — log into the Sunsynk web portal, go to Account Settings and disable MFA before configuring the integration
  • Some special characters in passwords can cause issues — try resetting to a password using only alphanumeric characters and common symbols

"Cannot connect to API"

  • Check that your HA server has outbound internet access on port 443
  • Verify you are using the correct API server: api.sunsynk.net for Sunsynk, pv.inteless.com for Deye/Inteless
  • The Sunsynk API occasionally has outages — check Sunsynk service status or community forums
  • Try the connection from your HA server: curl -I https://api.sunsynk.net

Integration keeps asking for credentials after restart

The integration stores credentials in the HA config entry (HA's built-in encrypted storage). If credentials are lost after restart, your HA secrets/storage may have an issue. Try deleting and re-adding the integration.

No data / sensors unavailable

All sensors show "Unavailable"

  1. Check the inverter is online in the Sunsynk app (dongle LED green, data updating in app)
  2. Go to Settings → Devices & Services → Sunsynk → (⋮) → Reload to force a fresh fetch
  3. Check logs for errors during the _async_update_data call
  4. The Sunsynk cloud itself may be slow — wait 10 minutes and try again

Sensors have old values / not updating

  • The Sunsynk cloud updates inverter data every ~5 minutes regardless of your HA refresh interval
  • If Last Cloud Update sensor is not advancing, the inverter is not sending data to the cloud (check dongle connection)
  • If Last Cloud Update advances but HA values are stale, check your Refresh Interval setting

Some sensors missing (MPPT, phases, battery slots)

These are dynamic sensors discovered on the first successful data fetch:

  • MPPT sensors (pv_mppt_1_power, etc.) — only created if the API returns MPPT data for your inverter
  • Phase sensors (grid_phase_1_voltage, etc.) — only for 3-phase inverters
  • Battery slot sensors (battery_slot_1_soc, etc.) — only if parallel battery packs report non-zero voltage

If the first data fetch failed, dynamic sensors are never registered. Fix the underlying issue (authentication, connectivity) and reload the integration. They will be created on the next successful fetch.

Writable settings not applying

Setting reverts immediately after writing

The integration requests a data refresh after each write. If the inverter rejects the value (e.g. out of range, firmware doesn't support it), the API returns the original value on the next fetch and the entity reverts. Check logs for API error responses.

"Failed to write setting" in logs

  • The inverter may be offline or not accepting commands
  • Some settings require related settings to be written together (e.g. battery settings are always written as a group — the integration handles this automatically, but make sure the current settings are readable)
  • Some settings only apply in certain work modes (e.g. time slot settings only matter when sys_work_mode is set to Time of Use)

Number entity shows wrong range or unit

The integration uses ranges from the API response. If your inverter firmware reports different min/max values, reload the integration after a successful data fetch.

Dashboard issues

Dashboard not appearing in sidebar

The auto-generated dashboard registration can fail if Lovelace's internal state is unusual. Check logs for Sunsynk: dashboard errors. Try reloading the integration. If it still doesn't appear, create the dashboard manually (see Dashboard).

Dashboard shows wrong entity IDs / entities missing

The dashboard is generated from the entity registry at setup time. If entities were registered after the dashboard was generated (e.g. dynamic MPPT sensors appeared later), reload the integration to regenerate the dashboard.

Forecast cards not showing in dashboard

The forecast cards are only included in the auto-generated dashboard when forecast entities are registered at dashboard generation time. Steps:

  1. Confirm forecast is configured — Settings → Devices & Services → Sunsynk → Configure → check kWp is set
  2. Check that sensor.solar_forecast_today exists in Settings → Entities
  3. Reload the integration — Settings → Devices & Services → Sunsynk → (⋮) → Reload
  4. The dashboard will be regenerated including the forecast cards

Solar forecast issues

Forecast sensors show "Unavailable"

  • Check outbound internet access to api.open-meteo.com from your HA server
  • Look in logs for Open-Meteo request failed
  • Open-Meteo is free and rarely has outages, but it does happen — wait and it will retry in 30 minutes

Forecast kWh values seem too high or too low

  • Verify your panel kWp value — this is the peak DC power of all your panels combined (e.g. 20 panels × 400W = 8.0 kWp)
  • Adjust performance ratio — typical values: new system 0.80, older/dusty system 0.70, premium modern inverter 0.85
  • The forecast uses GHI (horizontal irradiance) and does not account for panel tilt or azimuth — tilted south-facing panels will usually outperform the forecast on clear days, while flat or north-facing panels may underperform

GHI/DNI sensors show 0 at night

This is correct. Open-Meteo returns 0 W/m² for irradiance during nighttime hours.

Multiple inverter issues

One inverter works, another shows unavailable

Each inverter is fetched independently. If one fails, the integration keeps the last known good data for that serial and logs an error. The working inverter continues updating normally. Check the failing inverter's serial number and its connectivity to the Sunsynk cloud.

Entities from two inverters are mixed up

Entity IDs are generated from the device alias (inverter name). If two inverters have the same alias, HA will append _2 to the second. Set unique aliases in the Sunsynk app for each inverter.

Reporting a bug

Open an issue at GitHub Issues and include:

  1. HA version (Settings → System → About)
  2. Integration version (HACS → Integrations → SunSynk HA Integration)
  3. Inverter model and firmware version (sensor.{prefix}_firmware_master_version)
  4. Relevant log lines (with debug logging enabled)
  5. Steps to reproduce the problem

Clone this wiki locally