home-assistant/core · error · ConfigEntryNotReady

{adapter_human_name(adapter, address)}: {err}

Error message

{adapter_human_name(adapter, address)}: {err}

What it means

ConfigEntryNotReady raised when HaScanner.async_start() throws RuntimeError or ScannerStartError (from bleak). The message prefixes the human adapter name so the underlying bleak error (device busy, operation not permitted, resource temporarily unavailable) is visible. Setup will be retried.

Source

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

    # 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
    entry.async_on_unload(async_register_scanner(hass, scanner, connection_slots=slots))
    await async_update_device(hass, entry, adapter, details)
    try:
        await scanner.async_start()
    except (RuntimeError, ScannerStartError) as err:
        raise ConfigEntryNotReady(
            f"{adapter_human_name(adapter, address)}: {err}"
        ) from err
    entry.async_on_unload(entry.add_update_listener(async_update_listener))
    entry.async_on_unload(scanner.async_stop)
    return True


async def async_update_listener(hass: HomeAssistant, entry: ConfigEntry) -> None:
    """Handle options update."""
    await hass.config_entries.async_reload(entry.entry_id)


async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
    """Unload a config entry."""
    return True

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Read the trailing bleak message — 'Operation not permitted' points to container privileges, 'Resource temporarily unavailable' to adapter busy/down
2. Stop competing scanners (bluetoothctl scan on, other HA instances, hcitool lescan)
3. In Docker, run with network capabilities and pass the adapter through (or use HAOS which handles this); ensure bluetoothd is active
4. Reset the adapter: sudo hciconfig hci0 reset (or replug), then reload the entry

from bleak import BleakScanner  # underlying failure source
# The integration already wraps async_start and raises ConfigEntryNotReady;
# consumers should treat it as transient:
try:
    await async_setup_entry(hass, entry)
except ConfigEntryNotReady as err:
    logger.warning("Bluetooth scanner failed to start: %s; will retry", err)

When it happens

Trigger: Another process (e.g. a second HA instance, bluetoothctl, or a stale scanner) holds the adapter; insufficient capabilities in a container (no NET_ADMIN/NET_RAW); DBus/bluez problems; adapter in a bad state after suspend/resume.

Common situations: Docker/HAOS container missing bluetooth pass-through or privileges; bluez daemon not running; two integrations scanning on one adapter with too few connection slots; suspend/resume leaving hci0 down.

Related errors

• Bluetooth adapter {adapter} with address {address} not found
• Source {source} not found
• {err}
• Could not find Airthings device with address {address}: {rea
• Unable to fetch data for migration: {err}

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