home-assistant/core · error · HomeAssistantError

Unable to load mfa module {module_name}: {err}

Error message

Unable to load mfa module {module_name}: {err}

What it means

Raised as HomeAssistantError by _load_mfa_module (homeassistant/auth/mfa_modules/__init__.py:159) when async_import_module raises ImportError for homeassistant.auth.mfa_modules.{module_name}. This means the module name does not correspond to a Python module in that package — most often a bad key under auth_mfa_modules in configuration.yaml. The underlying ImportError is logged and chained.

Source

Thrown at homeassistant/auth/mfa_modules/__init__.py:159

        _LOGGER.error(
            "Invalid configuration for multi-factor module %s: %s",
            module_name,
            humanize_error(config, err),
        )
        raise

    return MULTI_FACTOR_AUTH_MODULES[module_name](hass, config)


async def _load_mfa_module(hass: HomeAssistant, module_name: str) -> types.ModuleType:
    """Load an mfa auth module."""
    module_path = f"homeassistant.auth.mfa_modules.{module_name}"

    try:
        module = await async_import_module(hass, module_path)
    except ImportError as err:
        _LOGGER.error("Unable to load mfa module %s: %s", module_name, err)
        raise HomeAssistantError(
            f"Unable to load mfa module {module_name}: {err}"
        ) from err

    if hass.config.skip_pip or not hasattr(module, "REQUIREMENTS"):
        return module

    processed = hass.data.get(DATA_REQS)
    if processed and module_name in processed:
        return module

    processed = hass.data[DATA_REQS] = set()

    await requirements.async_process_requirements(
        hass, module_path, module.REQUIREMENTS
    )

    processed.add(module_name)
    return module

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Fix the key under auth_mfa_modules in configuration.yaml to a real module (e.g. `totp:` or `notify:`)
2. Check the logged preceding line 'Unable to load mfa module %s: %s' for the exact ImportError reason
3. Restart Home Assistant after correcting the config

Example fix

# before (configuration.yaml)
auth_mfa_modules:
  - otp:   # no such module

# after
auth_mfa_modules:
  - totp:

from homeassistant.auth import mfa_modules
valid = set(mfa_modules.MULTI_FACTOR_AUTH_MODULES) | set(getattr(mfa_modules, "AUTH_MULTI_FACTOR_AUTH_MODULES", {}))
configured = [m for m in my_config]
assert set(configured) <= valid

try:
    await auth_manager.async_get_auth_mfa_module(module_id)
except HomeAssistantError as err:
    if not str(err).startswith("Unable to load mfa module"):
        raise
    # surface config error to user

When it happens

Trigger: configuration.yaml lists an unknown module under auth_mfa_modules (typo like `otp:` instead of `totp:`); referencing a custom mfa module that is not shipped inside homeassistant.auth.mfa_modules; module file removed/renamed in an upgrade.

Common situations: Hand-edited configuration.yaml after reading outdated docs; version upgrades that rename modules; custom integrations trying to register MFA modules by name only.

Related errors

• Unable to load auth provider {provider}: {err}
• trusted_networks is not configured
• User is not active
• System generated users cannot have refresh tokens connected
• System generated users can only have system type refresh tok

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