home-assistant/core · error · ConfigEntryNotReady

Bluetooth adapter {adapter} with address {address} not found

Error message

Bluetooth adapter {adapter} with address {address} not found

What it means

ConfigEntryNotReady raised in the bluetooth integration's setup when manager.async_get_adapter_from_recover(address) returns None: no local Bluetooth adapter with the entry's MAC address (its unique_id) was found. Note the message interpolates the adapter variable at that point, so it reads 'adapter None' — the address is the useful field. HA retries setup with backoff.

Source

Thrown at homeassistant/components/bluetooth/__init__.py:399

        details = AdapterDetails(
            address=address,
            product=entry.data.get(CONF_SOURCE_MODEL),
            manufacturer=manufacturer,
        )
        await async_update_device(
            hass,
            entry,
            source_entry.title,
            details,
            entry.data.get(CONF_SOURCE_DEVICE_ID),
        )
        return True
    manager = _get_manager(hass)
    address = entry.unique_id
    assert address is not None
    adapter = await manager.async_get_adapter_from_address_or_recover(address)
    if adapter is None:
        raise ConfigEntryNotReady(
            f"Bluetooth adapter {adapter} with address {address} not found"
        )
    adapters = await manager.async_get_bluetooth_adapters()
    details = adapters[adapter]
    mode = resolve_scanning_mode(entry.options)
    # AUTO needs passive scanning support to flip on demand; without it
    # the scanner would start passive on hardware that can't do passive.
    if mode is BluetoothScanningMode.AUTO and not details.get(ADAPTER_PASSIVE_SCAN):
        mode = BluetoothScanningMode.ACTIVE
    scanner = HaScanner(mode, adapter, address)
    scanner.async_setup()
    if entry.title == address:
        hass.config_entries.async_update_entry(
            entry, title=adapter_title(adapter, details)
        )
    slots: int = details.get(ADAPTER_CONNECTION_SLOTS) or DEFAULT_CONNECTION_SLOTS
    # Register the scanner before starting so
    # any raw advertisement data can be processed

View on GitHub (pinned to 58a3fdb3ea)

Solutions

Plug the adapter back in / verify it is visible: hciconfig -a or lsusb, then reload the Bluetooth config entry
If the hardware changed permanently, delete the old Bluetooth config entry and let HA rediscover the new adapter (new unique_id)
For late enumeration, just wait for the retry or restart HA after the dongle is up
In containers, ensure the adapter is passed through and privileged enough to access /dev/hci*

Defensive patterns

Strategy: retry

Validate before calling

from bluetooth_adapters import get_adapters  # or manager API

async def adapter_with_address_present(manager, address: str) -> bool:
    return await manager.async_get_adapter_from_address_or_recover(address) is not None

Try / catch

# Integration raises ConfigEntryNotReady itself; rely on HA's retry loop.
# Guard wrappers by checking adapter presence first:
adapter = await manager.async_get_adapter_from_address_or_recover(address)
if adapter is None:
    logger.info("Adapter for %s missing; waiting for retry", address)
    raise ConfigEntryNotReady(f"Bluetooth adapter with address {address} not found")

Prevention

Pin the adapter MAC by using the same physical dongle across restores/migrations
Delete stale bluetooth entries after migrating hardware so discovery recreates them

When it happens

Trigger: The USB Bluetooth dongle was unplugged or failed at boot; the adapter's MAC changed (different dongle swapped in); the entry was migrated from another host (e.g. restored backup) whose adapter address differs; adapter not yet enumerated when HA started.

Common situations: SD card/container migrated to new hardware; dongle moved to another USB port and re-enumerated late; dongle dead; passive-scan USB stick not bound to btusb yet.

Related errors

AI-assisted analysis of home-assistant/core@58a3fdb3ea (2026-08-14). Data as JSON: /api/errors/f9a2a1f311282017. Report an issue: GitHub.