home-assistant/core · error · ConfigEntryError

serial_mismatch

serial_mismatch

Error message

The serial number for {device} doesn't match the one in the configuration. It's possible that the two Brother printers have swapped IP addresses. Restore the previous IP address configuration or reconfigure the devices with Home Assistant.

What it means

ConfigEntryError with translation_key 'serial_mismatch', raised after the first coordinator refresh when the discovered printer's serial (brother.serial) does not equal the config entry's unique_id. The integration keys configuration by serial, so a mismatch means the entry is now talking to a physically different printer.

Source

Thrown at homeassistant/components/brother/__init__.py:52

    try:
        brother = await Brother.create(
            host, port, community, printer_type=printer_type, snmp_engine=snmp_engine
        )
    except (ConnectionError, SnmpError, TimeoutError) as error:
        raise ConfigEntryNotReady(
            translation_domain=DOMAIN,
            translation_key="cannot_connect",
            translation_placeholders={
                "device": entry.title,
                "error": repr(error),
            },
        ) from error

    coordinator = BrotherDataUpdateCoordinator(hass, entry, brother)
    await coordinator.async_config_entry_first_refresh()

    if brother.serial.lower() != entry.unique_id:
        raise ConfigEntryError(
            translation_domain=DOMAIN,
            translation_key="serial_mismatch",
            translation_placeholders={
                "device": entry.title,
            },
        )

    entry.runtime_data = coordinator

    await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)

    return True


async def async_unload_entry(hass: HomeAssistant, entry: BrotherConfigEntry) -> bool:
    """Unload a config entry."""
    return await hass.config_entries.async_unload_platforms(entry, PLATFORMS)

View on GitHub (pinned to 58a3fdb3ea)

Solutions

Set DHCP reservations for each printer so each keeps a stable, distinct IP
Reconfigure the entry's host to point at the original printer (Options flow / reconfigure)
If the original printer is gone for good, delete the entry and set up a new one for the replacement

Defensive patterns

Strategy: validation

Validate before calling

# Before relying on the entry, compare reported serial vs entry unique_id
serial = coordinator.brother.serial.lower()
expected = entry.unique_id
serial_matches = (serial == expected)
if not serial_matches:
    # stop automations; fix IP assignments before proceeding

Prevention

Assign DHCP reservations per printer MAC so IPs never swap
After any router change, verify each Brother entry still reaches its original serial
Never reuse an old IP for a replacement printer without deleting the old HA entry

When it happens

Trigger: Two Brother printers swapped IP addresses (DHCP renewal), so the entry's host now resolves to the other printer; entry configured against a printer that was replaced by another unit reusing the old IP.

Common situations: Classic swapped-IPs scenario with two identical Brother printers on one network; replacing a failed printer with a new one at the same IP; restoring a router that hands out different leases.

Related errors

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