Configuration Issues¶
Resolving problems with saving configuration, validation errors, and configuration persistence.
Validation Errors When Saving¶
When a configuration change fails validation, the error message specifies the failing field. The previous configuration remains unchanged -- no partial saves occur.
Common Validation Errors¶
| Symptom | Likely Cause |
|---|---|
| Error on a load entry | Missing required entity ID, or param_min >= param_max for dynamic loads |
| Error on energy entities | An entity ID field was left empty |
| Duplicate load IDs | Two loads share the same id field |
| Priority references unknown load | The load_id in a priority entry does not match any configured load |
To resolve:
- Read the error message carefully -- it identifies the specific field that failed.
- Fix the flagged field in Settings.
- Resubmit the configuration.
Tip
For dynamic loads, ensure param_min is strictly less than param_max. A common mistake is setting both to the same value, which leaves the engine no room to adjust the setpoint.
Configuration Not Persisting After Restart¶
If your configuration reverts to defaults after restarting the add-on, the configuration file is not being written to persistent storage.
HA Add-on Installation¶
The configuration is stored at /config/addons/hanergy/config.json inside the container. For this path to be writable:
- The add-on manifest must include the correct volume mapping. The official add-on includes this by default.
- The HA host's configuration directory must not have been manually created with incorrect file permissions.
To verify: restart the add-on, then check Settings > Devices and Settings > Priorities. If they are empty, the configuration file is not being persisted.
Docker Installation¶
Ensure the Docker volume mount is correct:
If the volume mount is missing or points to a temporary directory, configuration changes will be lost on container restart. Use a named volume or a host directory mount to persist data.
Configuration Changes Not Taking Effect¶
Hanergy supports live configuration reload -- changes saved through the UI take effect on the next evaluation cycle without restarting the add-on.
If changes do not seem to take effect:
- Wait one evaluation cycle (default: 10 seconds) after saving.
- Check for validation errors. If the save returned an error, the old configuration is still active.
- Verify in the Decision Timeline. After saving, the next timeline entry should reflect the updated configuration (new loads, changed thresholds, etc.).
- Clear browser cache. In rare cases, the UI may display stale data. Refresh the page or open it in an incognito window.