[Bug]: aioesphomeapi declared without version constraint breaks all ESPHome devices in Home Assistant

[andreasfedele]

Version

v3.1.0

Connection type

ESPHome BLE proxy

Bug description

Summary

pyproject.toml lists aioesphomeapi with no version constraint. When Home Assistant
installs this integration's requirements, pip pulls the latest PyPI release on top of the
version shipped with HA Core. Since aioesphomeapi ships compiled Cython extensions, this
leaves modules from two different builds side by side in the same Python process. Every
ESPHome device in the installation then fails to connect — not just the Bluetooth proxy
used by this integration.

Environment

• Home Assistant Core 2026.7.4 (HA OS, Python 3.14, amd64)
• geberit-aquaclean 3.1.2
• ESPHome devices on 2026.7.3 and 2026.4.0, all reachable, port 6053 open

What happens

After a "Restart Home Assistant", all ESPHome devices go unavailable and never recover.
Only a full "Reboot system" brings them back, and only sometimes — the outcome depends on
module import order, so it behaves like a race condition. Uninstalling this integration
resolves it completely and permanently.

Logs

RuntimeWarning: aioesphomeapi.connection.APIConnection size changed, may indicate
binary incompatibility. Expected 224 from C header, got 232 from PyObject

ERROR [aioesphomeapi.reconnect_logic] Can't connect to ESPHome API for @ :
Error while finishing connection: aioesphomeapi._frame_helper.packets does not export
expected C function make_noise_packets (UnhandledAPIConnectionError)

ERROR [aioesphomeapi.reconnect_logic] Can't connect to ESPHome API for @ :
Error while finishing connection: 'reduce_cython' (UnhandledAPIConnectionError)

How to reproduce

1. Working HA installation with ESPHome devices
2. Install this integration, pointing it at an ESPHome Bluetooth proxy
3. Restart Home Assistant Core
4. All ESPHome devices are unavailable; the devices themselves stay reachable and accept
   TCP connections on port 6053

What I ruled out

Network, Wi-Fi, mDNS, device firmware, stale IP addresses, /config/deps, and
ha core rebuild — the rebuild does not help because the conflicting version is
reinstalled on the next start. Disabling the integration is not enough either; HA still
installs requirements of disabled entries. Only uninstalling fixes it.

Suggested fix

aioesphomeapi is managed by Home Assistant Core and should not be declared as a
dependency of a custom integration at all — the integration can rely on the version Core
provides. If it must stay, pin it to exactly the version HA Core ships, and update that pin
alongside HA releases.

Relevant log output

Config (redacted)

[andreasfedele]

Not a simple version mismatch

I added "aioesphomeapi==45.3.1" (the version HA Core 2026.7.4 requires) to this
integration's manifest.json and ran ha core rebuild. No change — the same
size changed / make_noise_packets / __reduce_cython__ errors appear on the next restart.

So pinning the version does not help. This suggests aioesphomeapi gets rebuilt from
source when pip installs the package from the git URL, producing a second binary build
of the same version rather than a different version. A prebuilt wheel would avoid this.

Also ruled out: ha core rebuild alone, and downgrading HA Core to 2026.7.2.

[mundschenk-at]

I've also noticed the issue (and have been slowly removing HACS integrations to find the culprit).

[chriguschneider]

Corroborating report from a different environment (HA OS / aarch64 / Core 2026.8.3 / Python 3.14.6)

Independent reproduction that confirms this bug, plus a few extra data points that may help nail the fix.

Environment

• Home Assistant OS 18.2, Raspberry Pi 5 (aarch64), Supervisor 2026.07.5
• HA Core 2026.8.3, Python 3.14.6
• geberit-aquaclean 3.1.2
• Two Noise-encrypted ESPHome devices went unavailable; the devices themselves stayed online (port 6053 open, and the ESPHome CLI connected to them fine the whole time).

Confirmed mechanism, with exact versions

• HA Core's esphome / bleak_esphome integrations pin aioesphomeapi==45.6.1.
• In the broken state, pip show aioesphomeapi reported 45.12.0, with Required-by: bleak-esphome, geberit-aquaclean. So the unpinned requirement pulled 45.12.0 on top of Core's 45.6.1, exactly as described in the report.

Error variants observed (both originate in the noise frame-helper import, _import_noise_frame_helper -> _frame_helper/noise):

ValueError: aioesphomeapi.connection.APIConnection size changed, may indicate binary incompatibility. Expected 240 from C header, got 232 from PyObject
...
UnhandledAPIConnectionError: Error while finishing connection: '__reduce_cython__'

Note "Expected 240" here vs "Expected 224" in the original report: different colliding builds, same failure mode. Because the failing path is the noise handshake, it is specifically Noise-encrypted API connections that break.

Recovery behavior (adds nuance to the "rebuild does not help" point)

• In our case ha core rebuild followed by a separate ha core restart did recover it (twice). After the clean rebuild, pip show aioesphomeapi reported the Core-pinned 45.6.1 again and all devices reconnected.
• But it is not durable, and this matches the race-condition behaviour you noted: the very next HA Core update (2026.8.2 -> 2026.8.3) recreated the container overnight, re-ran the source install, re-upgraded aioesphomeapi to 45.12.0, and broke everything again. So a rebuild is only a temporary recovery, consistent with "the conflicting version is reinstalled on the next start."

Why the source rebuild is fragile here (contributing upstream factor)

• aioesphomeapi currently ships no cp314 (Python 3.14) wheels on PyPI (the classifiers list 3.11 / 3.12 / 3.13 / 3.15). Installing the unpinned dependency from the git URL therefore forces a source build under Python 3.14, which is where the inconsistent Cython artifacts come from.
• Evidence of an incomplete build even in the working 45.6.1 state: aioesphomeapi/_zc_listener.cpython-314-aarch64-linux-musl.so is absent, and HA logs No module named 'aioesphomeapi._zc_listener' ... continuing without mDNS-triggered reconnects.

On the suggested fix
+1 to dropping the aioesphomeapi dependency and relying on the version HA Core already provides. Given @andreasfedele's finding that pinning to the exact Core version still rebuilt from source into a second binary build of the same version, a pin alone may be insufficient as long as the package is installed from a git URL that triggers a source compile on 3.14. Not declaring aioesphomeapi at all avoids both the version override and the source rebuild.

Happy to provide full tracebacks or run further diagnostics if helpful.

[geraldbaeck]

Confirmed independently on HA OS, with the mechanism pinned down. Adding two things the thread doesn't have yet.

Environment: HA Core 2026.8.3 (Python 3.14), geberit-aquaclean v3.1.2 via HACS. Core pins aioesphomeapi==45.6.1 and bleak-esphome==3.9.7.

Symptom matched exactly — every Noise-encrypted ESPHome device dead for 4 days, starting 78 seconds after an HA restart:

RuntimeWarning: aioesphomeapi.connection.APIConnection size changed, may indicate
  binary incompatibility. Expected 232 from C header, got 240 from PyObject
ModuleNotFoundError: No module named 'aioesphomeapi._zc_listener'
KeyError: '__reduce_cython__'   (noise.py line 1, in init)

---

1. Why pip upgrades it at all.

An unpinned requirement is satisfied by any installed version, so pip would normally leave Core's pin alone — which makes the failure look implausible on paper. But homeassistant/util/package.py:

def install_package(package, upgrade=True, target=None, constraints=None, timeout=None):
    ...
    if upgrade:
        args.append("--upgrade")

upgrade defaults to True. So processing this package's requirements actively pulls aioesphomeapi to the newest PyPI release over Core's pin. That's the missing link.

2. Filesystem proof that it happened.

Inside the HA container, every package untouched since the image build shares one mtime:

bleak_esphome-3.9.7.dist-info    Aug 21 22:50   <- image baseline
noiseprotocol-0.3.1.dist-info    Aug 21 22:50
AEMET_OpenData / Crypto / ...    Aug 21 22:50

aioesphomeapi/                   Aug 24 09:43   <- rewritten at runtime
aioesphomeapi-45.6.1.dist-info/  Aug 24 09:43
container StartedAt              Aug 24 09:42:25

async_process_requirements only installs a requirement when the installed version does not already satisfy it. So that 09:43 rewrite is itself evidence the version present beforehand was not 45.6.1 — the restart didn't clear a glitch, it detected a wrong version and reinstalled Core's pin.

Also confirmed they share one slot, not two:

$ pip show aioesphomeapi
Version: 45.6.1
Location: /usr/local/lib/python3.14/site-packages
Required-by: bleak-esphome, geberit-aquaclean

---

Why this is nastier than it looks: the next restart silently repairs it, so it presents as intermittent rather than persistent. It only reappears the next time the component's requirements are reinstalled (Core update, HACS update). Ours ran 4 days before anyone connected the log spam to dead devices — the first traceback line looks cosmetic; the cause is in the last two.

#47 looks like the right shape to me. Dropping it from base deps and letting HA Core provide it beats pinning, which would mean chasing every Core bump.

[chriguschneider]

For anyone landing here: PR #47 fixes this by moving aioesphomeapi into an optional [esphome] extra, so Home Assistant Core no longer gets its aioesphomeapi==45.6.1 pin overridden. The PR is mergeable and CI is clean — a merge + release would close this out.

As a temporary local workaround until then, you can point the integration's manifest.json requirement at the fixed commit and rebuild:

geberit-aquaclean @ git+https://github.com/chriguschneider/geberit-aquaclean@882064aa6c044e9ca89caf98b88ed072c061a271

then ha core rebuild followed by a separate ha core restart.