Deprecate use of config entry listener with reloading methods in config entries

[gjohansson-ST]

Breaking change

Proposed change

When using a config entry listener in combination with async_update_reload_and_abort or _abort_if_unique_id_configured there might be a double reload of the integration, or at least a race in between.

This is now deprecated and will be changed raise error in 2026.12

(only unifi still has this from core integrations, which has a PR open to fix it)

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New integration (thank you!)
• New feature (which adds functionality to an existing integration)
• Deprecation (breaking change to happen in the future)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests

Additional information

• This PR fixes or closes issue: fixes #
• This PR is related to issue:
• Link to documentation pull request:
• Link to developer documentation pull request: The use of config entry listener with reloading methods in config flow developers.home-assistant#3082
• Link to frontend pull request:

Checklist

• I understand the code I am submitting and can explain how it works.
• The code change is tested and works locally.
• Local tests pass. Your PR cannot be merged unless tests pass
• There is no commented out code in this PR.
• I have followed the [development checklist][dev-checklist]
• I have followed the [perfect PR recommendations][perfect-pr]
• The code has been formatted using Ruff (ruff format homeassistant tests)
• Tests have been added to verify that the new code works.
• Any generated code has been carefully reviewed for correctness and compliance with project standards.

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated for [www.home-assistant.io][docs-repository]

If the code communicates with devices, web services, or third-party tools:

• The [manifest file][manifest-docs] has all fields filled out correctly.
  Updated and included derived files by running: python3 -m script.hassfest.
• New or updated dependencies have been added to requirements_all.txt.
  Updated by running python3 -m script.gen_requirements_all.
• For the updated dependencies a diff between library versions and ideally a link to the changelog/release notes is added to the PR description.

To help with the load of incoming pull requests:

• I have reviewed two other [open pull requests][prs] in this repository.

[Copilot]

Pull request overview

This PR adds a deprecation warning path to discourage using config entry update listeners together with config-entry update helpers that also schedule reloads, since that combination can cause double reloads/races.

Changes:

• Log a report_usage(..., breaks_in_ha_version="2026.11.0") warning when _abort_if_unique_id_configured(...) updates an entry that has update listeners and will also reload.
• Log a similar warning from async_update_reload_and_abort(...) before scheduling a reload.
• Add a test that verifies the warning is logged for both the _abort_if_unique_id_configured (reauth) and async_update_reload_and_abort (reconfigure) paths when an update listener exists.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
homeassistant/config_entries.py	Adds report_usage logging for the deprecated “update listener + reload helper” pattern.
tests/test_config_entries.py	Adds coverage to confirm the deprecation warning is emitted when an update listener is present.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

[MartinHjelmare]

There's a related test failure. Otherwise looks good.

I suggest we merge this after the beta cut so any remaining integrations have a release cycle to address this. We should also publish a dev blog. Bump the stop working month.

[home-assistant]

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

[MartinHjelmare]

I can't add inline comments at the moment (thanks GitHub). Please bump the release date when this will stop working to 2026.12.0. Ie 6 months from 2026.6.0 when this PR will be released.

[gjohansson-ST]

I can't add inline comments at the moment (thanks GitHub). Please bump the release date when this will stop working to 2026.12.0. Ie 6 months from 2026.6.0 when this PR will be released.

Mistake on my side, I was counting it wrongly.
Now updated

[MartinHjelmare]

Thanks!

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.