BleakClient.stop_notify() documentation seems not relevant for MAC OS

[EasyRiderr]

The BleakClient.stop_notify() documentation says:

Notifications are stopped automatically on disconnect, so this method does not need to be called unless notifications need to be stopped some time before the device disconnects.

But on MAC (Apple M2 Pro with macOS Tahoe v26.4.1), when bleak connects to a BLE peripheral, enables notifications, disconnects then reconnects and try to enable notifications, the following errors is raised:

File "/Users/user/Library/Application Support/hatch/env/virtual/project/hoVqGm6Y/project/lib/python3.14/site-packages/bleak/backends/corebluetooth/client.py", line 382, in start_notify
    await self._delegate.start_notifications(
    ...<3 lines>...
    )
  File "/Users/user/Library/Application Support/hatch/env/virtual/project/hoVqGm6Y/project/lib/python3.14/site-packages/bleak/backends/corebluetooth/PeripheralDelegate.py", line 463, in start_notifications
    raise ValueError("Characteristic notifications already started")
ValueError: Characteristic notifications already started

The expected behavior would be no Exception raised. By the way, under Linux, everything is fine.

[dlech]

Can you share minimal code to reproduce the problem?

[Vodur]

The root cause is that on macOS, the PeripheralDelegate's _characteristic_notify_callbacks dict is not cleared on disconnect. CoreBluetooth does stop notifications at the OS level on disconnect, but bleak's internal tracking state isn't reset.

On reconnect, the same PeripheralDelegate instance is reused (since self._delegate is still set), and start_notifications() sees the stale entries and raises ValueError("Characteristic notifications already started").

The fix would be to clear the notification state in the disconnect callback:

def disconnect_callback() -> None:
    self.services = None
    assert self._delegate is not None

    # Clear notification tracking state
    self._delegate._characteristic_notify_callbacks.clear()
    self._delegate._characteristic_notification_discriminators.clear()

    for future in self._delegate.futures():
        try:
            future.set_exception(BleakError("disconnected"))
        except asyncio.InvalidStateError:
            pass

    if self._disconnected_callback:
        self._disconnected_callback()

Linux doesn't have this issue because BlueZ handles notification cleanup at the D-Bus level independently of bleak's state tracking.

[dlech]

Reconnecting using the same BleakClient object is something that has never worked well in Bleak because of odd cases like this.

If I ever have enough time, I would like to have a long, hard look at how all of the different OSes handle reconnecting to a disconnected device to try to normalize this in Bleak.

We've long know that in BlueZ, if you use the same D-Bus connection to reconnect to a device, it will automatically enable notifications again. It sounds like macOS has a similar behavior.

So ideally, we would have an auto-reconnect feature where if we get a device disconnected notification from the OS that we would try to reconnect first before calling the disconnect callback.

Windows already does this at the OS level, so it would be nice if we could make BlueZ and macOS behave the same from Bleak's point of view.

In the meantime, if someone wants this fixed bad enough, I would consider a pull request that has test coverage. Otherwise, use the suggested workaround of creating a new BleakClient object.

[dlech]

Interestingly, I've just realized that this was reported long ago in #762, but I never really understood the issue at the time.