Troubleshooting and Diagnostics

Troubleshooting and Diagnostics

Setup messages

Message	Cause and what to do
Modbus did not answer. Without the web API, switch Modbus TCP on in the inverter first and set the SunSpec model type to int + SF.	An entry Without the web API could not read the inverter over Modbus. Set the inverter's Modbus by hand (see Installation and Setup). With float as the model type the inverter model is not found either.
Failed to connect	With a Web API role: the inverter did not answer, over Modbus or its web interface, or the login could not be made. Check the host and that the inverter is on.
Login failed for the selected Web API role.	The inverter refused the password of the selected role. Use the local customer or technician password, not the Solar.web login (see Web API). In one reported case, a correct password was refused until the inverter had been restarted. If nothing else helps, this may be worth a try.
A password is required for the selected Web API role.	No password was entered and no stored token exists for this host and role.
Another entry already uses this host.	One entry per inverter.
Unsupported hardware. See logs.	The device's SunSpec common model does not name Fronius as the manufacturer.
Could not determine the Home Assistant IP.	The Modbus IP restriction choice Restrict control to allowed hosts and allow this Home Assistant needs the address Home Assistant reaches the inverter from, and it could not be found.
Minimum update interval is 5 seconds.	The Modbus update interval is below 5 s.
The grid meter power interval must be shorter than the update interval, or 0.	The grid meter power interval is set, but not below the update interval.
Only an inverter announced with an IPv4 address can be added from discovery.	Add an inverter that announces an IPv6 address only by hand, with its IPv4 address.
Setting up this inverter is already in progress.	Another setup dialog for this inverter, such as its discovery card, is still open; finish or close it.
Invalid host address	Enter the inverter's IP address or host name.
Invalid port number	The port must be a valid TCP port.
Unknown error	Unexpected; the log has the details. Please report it as an issue.

Messages when you set a value

Message	What to do
The inverter is no longer in the selected storage mode, for example after a schedule or another controller changed it. Select the mode again.	Select Storage Control Mode again, then set the value.
A limit of 0 W would block charging and discharging at once, which the inverter refuses.	Keep one direction open (see Battery Control).
The inverter holds a combined charge and discharge limit, for example from another controller, that this grid power would exceed. Select the storage mode again to set the power freely.	Select the mode again.
The charge limit cannot be changed in the current storage mode. (and the like)	The current storage mode does not use this control; select a mode that does first.
This value can only be changed while self-consumption optimisation is Manual. / … while the Web API SoC mode is Manual.	Set the named select (Self-consumption optimisation or Web API SoC mode) to Manual first.
The SoC minimum must not exceed the SoC maximum.	Lower the minimum or raise the maximum first.
The AC limit cannot be set: the inverter has not reported its maximum power yet.	Wait for a poll that reads model 121.
This control needs the technician role. Choose it via Configure.	The export soft limit needs the technician role.
The Fronius Web API rejected the login. Log in again when Home Assistant asks for it on the integration.	Follow Reauthentication required on the integration.
The storage mode is set to Charge from Grid, but …	The mode is set, but grid charging could not be allowed in the inverter's battery configuration; allow it there, or log in again (see Battery Control).
The Modbus storage reserve is set, but the inverter's web interface did not take it as SoC minimum; the two minimums now differ	Set one of the two minimums again (see Battery Control).
The inverter's web interface did not answer.	Check that the inverter is on and reachable.
Writing to the inverter failed: …	The inverter did not take the write over Modbus or its web interface: it is busy, offline or refused it. For a web interface setting the text after the colon names the fields it refused, for example permissionFailure when the chosen role may not change them. Check that it answers and try again.
The value was refused: …	The inverter or the integration refused the value; the text after the colon says why.
The value must be between … and …. / The value must be a whole number.	Enter a value inside the range, as a whole number where asked.

Reauthentication

Home Assistant shows Reauthentication required on the integration when an entry has no valid token for its host and role, for example after the password was changed on the inverter, or for an entry migrated from an older version. Follow it to enter the role's password again, or choose Without the web API to run the entry on Modbus alone. Until then the entities that need the login stay unavailable. An entry that starts without a valid token does not poll the inverter's web interface at all, so the component sensors, the events, the energy management outputs and the throttle reason's limit flags are missing too, and only the first smart meter is read.

Repair notices

• Disable Fronius Solar API on older firmware appears on firmware below 1.40.7-1 with the Solar API switched on, for an entry with a Web API role. The Solar API on such firmware caused outages on GEN24 inverters. The notice offers to switch the Solar API off until the inverter is updated, or to ignore the warning. It goes away once the firmware is updated or the Solar API is off.
• Old Fronius login notice is left from an earlier version of the integration. Confirm it to remove it; Home Assistant now asks for a new login on the integration itself when one is needed.

Logs

• A part that stops answering - the inverter, a meter, the battery, the Web API - is logged once when it fails and once when it answers again.
• Web API errors name the error type, not the host.
• For more detail, enable debug logging on the integration's page, reproduce the problem and disable it again; Home Assistant then offers the log for download.

Diagnostics

Settings → Devices & services → Fronius Modbus → device → Download diagnostics. The download includes which parts the last poll read and which failed, the Web API values, and the raw SunSpec register map. Serial numbers and the Modbus restriction IP are redacted. It also works while the inverter is offline, as long as the entry was loaded before it went offline. Attach it to an issue after looking through it.

The inverter dump tool

On Windows, tools/inverter_dump.bat collects everything the inverter reads out, for a device that is not verified yet. It starts inverter_dump.ps1 next to it; both files are needed, nothing else is installed.

• It asks for the inverter's address and saves one JSON file next to the script: every status, component and Solar API endpoint, and the web interface's channel names and event texts, which answer without a login.
• On request it adds the configuration endpoints of the customer or technician login, and the raw SunSpec registers of the inverter and its meters over Modbus TCP (Modbus must be switched on). The password is asked for and not stored.
• It only reads: of the command endpoints it calls the login alone, and over Modbus it only reads registers. A device without the GEN24 web interface, such as a Datamanager, still gets its Solar API and Modbus read.
• Meters are looked for at units 200 to 209; for another meter offset, start inverter_dump.bat <address> -FirstMeterUnit <offset>.
• To look for a meter on every Modbus unit, start inverter_dump.bat <address> -AllUnits. This can take several minutes.
• By default serial numbers, IP and MAC addresses, host and system names are replaced with <redacted>, and the serial number in the SunSpec registers with zeros. Still look through the file before you share it.

Discovery

No card appears for an inverter that is already set up, one in another subnet without an mDNS repeater between them, or one announced with an IPv6 address only (see Installation and Setup).

Known limitations

• Models other than the verified setup (see Home) are untested.
• A module temperature or a limit sensor that appears later gets its entity at the next reload of the entry. A firmware update reloads the entry on its own.
• A module temperature entity that stays unknown for good, because the module is gone or because a development build created it as a placeholder, can be disabled. It cannot be deleted: the integration keeps every module the inverter once reported, so one incomplete answer cannot take a real module with its history.
• When the last smart meter is removed, its entities stay unavailable; delete them in Home Assistant, where they show as no longer provided. A device the inverter no longer reports, such as a removed meter or battery, can then be deleted on its device page. An empty meter list from the inverter is not taken as proof that no meter exists.
• While the SoC mode is Manual, the Modbus storage reserve cannot be changed while the Web API does not answer.
• The Web API cannot be reached through an IPv6 address; set the entry up with an IPv4 address or a host name.
• Scheduled charging and discharging in the inverter's web interface and the Modbus storage modes get in each other's way; turn the schedule off when using the modes.
• Firmware without the event endpoints leaves the event entities unknown or unavailable.