Enphase Envoy add-on doesn't work with new gateway

Third party integrations
1

A few weeks ago I replaced my Enphase gateway for a new one (the old one died after 5 years). Getting it to work with my microinverters was a pain, but in the end it works. All the Enphase apps/logins work and the data is reported properly again.

So now I want to re-add the gateway (different serial/IP) to my HAS. It did find it through the add-ons menu, so I configured it with my cloud login (username/password) to register it, and it says “Re-authentication was successful”.

Immediately after though, I get the problem you see in the attached screenshot.

I was able to manually login to my gateway at https://192.168.178.59 with the token I generated at Enphase, and then I am able to get the RestAPI reports to work (e.g. https://192.168.178.59/api/v1/production/inverters) through a browser. Nothing in HAS with the add-on seems to work.

You will notice a disabled gateway in the screenshot, that’s the old one. My plan is to rename the new one later so that the data gets merged with the old one, meaning I don’t lose all my historic data.

I need some guidance to debug this issue. I don’t know how to get this to work…

Screenshot_2025-12-29_11-31-43
Screenshot_2025-12-29_11-31-431130×546 44.2 KB

Screenshot_2025-12-29_11-38-12
Screenshot_2025-12-29_11-38-12662×367 18.2 KB

Screenshot_2025-12-29_16-57-02
Screenshot_2025-12-29_16-57-02196×302 5.32 KB

3

Did you ever figure this out / get any answers? I am struggling to get my Enphase system (just activated last week) to authenticate

4

Hi B_Raz,

No, sadly I did not. I did not give up either. I created a debug log of the re-authentication and will place it here when i have time (I have to check if there is personal info in it before I upload it).

I also had contact with Enphase Netherlands to check if I had the latest firmware, and they said yes (eliminating a long shot guess that this was old incompatible firmware). Now my less-long-shot guess is that the firmware is too new…

I also checked the plugin issues on github. I did not yet find an issue mentioning our problem…

We have still an option to explore:

  • Post an issue ticket on the github for the plugin

Maybe you can also post information about your gateway and firmware version in this homeassistant topic? And explain if you have exactly the same problem? Or creat a github ticket immediately if you can.

I will do it when I have time, but that might take a little while.

5

@baskapteijn,

is the new Envoy at the same IP as the previous one?

Replacing an existing Envoy with a new one while preserving historical data is indeed a more involved process. A recipe that was used recently, with a current HA version:

With the old envoy running, rename all entity ids that contain the old envoy serial number, to contain the new envoy serial serial number. That will update the meta tables in the database and the config_entries in the .storage area. All will continue to work with the old envoy, even if HA has to cycle.

Then when the moment to switch to the new envoy is there, remove the old envoy from ha. That will mark the entities as deleted_entities in the config_entries in the .storage area so they can be re-used when re-adding the same envoy again.

When adding the new Envoy, it doesn’t find it’s serial in the unique_id of any deleted entity and will create new entities with its serial in the entity_id and unique_id. As these entity_id’s already exist in the states and statistics meta data tables as result of the prior rename, all these now will be used for the new envoy data and prior long term history is linked to the new Envoy.

I’m a bit confused about the Envoy firmware, your screenshot shows D7.0.88, which is an old firmware. Current versions are D8.3.x (mine is at 8.3.5167), yet you write Enphase says it’s current.

Once you have the debug log please share so we can see what is going on.

@B_Raz,
Are you also replacing an existing Envoy or is your a new installation?

6

Hi, thanks for you reply.

My old gateway died, so I can’t do what you just described. Also, the new gateway (right now) is on a different (fixed) IP. The firmware, I agree, looks older. But maybe that’s related to the type of gateway I have, the model? I have to somehow trust the Enphase support that they told me correctly that there is no newer version for my gateway… It’s not auto updating either…

My plan was as follows:

  • Disable the old gateway in the integration (which I did)
  • Add the new gateway to the integration (which fails)
  • Then once that’s done, rename the new gateway to have the serial of the old one (in the name), hoping that the old data would be linked to the new one

But, I understand now that what you are proposing is the opposite.

  • Rename the old envoy name (of the disabled integration) to the new serial name
  • Then delete the integration
  • Then add the new gateway

My assumption was that deleting the old gateway first would mean deleting all data related to it. Is that incorrect?

And this still makes me wonder if it will even work adding the new gateway…

Here is the redacted log:

(note: replaced the serial with )

7

So we have 2 items to discuss, the authorization issue and the envoy long term data.

Next became a long story. Shortly, firmware d7.0.88 is known to fail with current HA and rename entity_ids of entity’s (not entity name or envoy name), remove old and add new envoy.

Authentication issue

As for the authorization issue, nothing wrong with your Enphase account or the token. In the log it can be seen that the token is retrieved and still valid.

When it tries to read data from the Envoy it receives the not-authorized status. This problem is typical for the D7.0.88 firmware. (See Github issue 148028). Which brings the question which firmware your old envoy was running?

The debug log shows you have no current transformers (CT) installed, Is your a Envoy-S non-metered EU one? I have such a one for 3 years now and it is on D8.3.5167 as of last summer.

Entity long term history

As for the names topic. The integration uses the serial number read from the Envoy to create all the names. Renaming the gateway itself will not help.

A starting Envoy integration uses the unique_id of entities to find these in the configuration data. The unique_id contains the envoy serial number. In the configuration data the entity_id stored. It uses the entity_id to find the history/statistics data. And the entity_id also contains the Envoy serial number.

If it can not find its entities through the use of the unique_id, like in the case of a different envoy serial number, it will create new entities with new unique_id and new entity_id, both with the new envoy serial number in it. It then checks if the entity_id exist in the history/statistics tables, and if not, create new empty entries and start using these. When adding a new Envoy with a different serial number, all entities get created with the new serial in the unique_id and the entity_id and all history starts fresh.

In current versions of HA, one can change the entity_id of an entity. When that is done, the entity_id in the configuration is changed as well as in the history/statistics tables. All still connected as before. Upon deleting the envoy, the history/statistical data is kept, only configuration data is marked as deleted.

By renaming the entity_ids of the old envoy to contain the new Envoy serial number, the new serial will be in the statistics/history entries. When then deleting the old envoy that data is kept. And when then adding the new envoy it will create new entities and connect these to the renamed entities in the statistics/history data.

So you will have to go into the entity list, find all old envoy entities and rename the entity_id (not the name, but the entity_id field). Then delete the old envoy and add the new one. (But that will fail because of above described issue)

8

Hi catsmanac,

Thank you so much for the detailed explanation. The migration path is clear to me now (old data re-use).

The thing that remains is the integration with my new gateway. The info you requested:

The gateway I ordered was listed as: Enphase Envoy-S Metered Gateway - ENV-S-EM-230
The sticker on the new gateway says: Enphase IQ Gateway Metered 2 ENV-S-EM-230

That means that I do have the coils (in the box), but I did not install them. That should be fine, I guess. My former (died) gateway was also installed without coils. But besides that, I think it was the same model (again, can’t verify because it’s on the scrapyard now).

I do not have a log/screenshot of the old gateway’s firmware, so sadly nothing I can show you there.

Now, the annoying thing is that it seems that Enphase support is lying (or lazy), and it does seem that there should be newer firmware. I am not the person with full access to this gateway (admin) because my installer guy is. So I’m not sure how to update the firmware to whatever is the latest right now…

9

Firmware release notes are here. Even if you have older micro-inverter types it seems 7.6 or 8.2 should be possible.

The envoy is connected to the internet and communicates with the Enphase web-site to send dat for the portal or app?

10

Thanks.

Yes the envoy is connected to the internet, it communicates with the Enphase web-site and enlighten app. All seems to be working fine (as before with the old gateway). However, no automatic update is triggered. I have read online that sometimes the automatic update won’t trigger (but that’s really hear-say), so I figured my installation guy (with more rights) has to do it. I send him an e-mail just now asking if he can have a look. This link shows a way to do it for people with his rights on my system:

https://support.enphase.com/s/article/How-do-I-update-the-Envoy-software-using-Enlighten-Manager

My assumption is that I can’t do it, he has to do it.

Or is there another way?

11

No, not that I know off. As far as I know you ether need to have a DIY/Installer account, an installer that does it for you, or Enphase do it. Or Enphase pushes it whenever they feel like it, that’s how mine is updated each time.

12

Alright, then I will push for updates from either him or Enphase. I think you answered all my/our questions. If I get new firmware, I’ll update this ticket with my future endeavours (with getting the integration to work).

13

While at it, I added the replacement process to the documentation.

14

That is awesome, that will help me and others in the future for sure. Thank you!