{"record":{"id":"09663d49ed96a9a0","repo":"home-assistant/core","slug":"unable-to-load-mfa-module-module-name-err","errorCode":null,"errorMessage":"Unable to load mfa module {module_name}: {err}","messagePattern":"Unable to load mfa module (.+?): (.+?)","errorType":"exception","errorClass":"HomeAssistantError","httpStatus":null,"severity":"error","filePath":"homeassistant/auth/mfa_modules/__init__.py","lineNumber":159,"sourceCode":"        _LOGGER.error(\n            \"Invalid configuration for multi-factor module %s: %s\",\n            module_name,\n            humanize_error(config, err),\n        )\n        raise\n\n    return MULTI_FACTOR_AUTH_MODULES[module_name](hass, config)\n\n\nasync def _load_mfa_module(hass: HomeAssistant, module_name: str) -> types.ModuleType:\n    \"\"\"Load an mfa auth module.\"\"\"\n    module_path = f\"homeassistant.auth.mfa_modules.{module_name}\"\n\n    try:\n        module = await async_import_module(hass, module_path)\n    except ImportError as err:\n        _LOGGER.error(\"Unable to load mfa module %s: %s\", module_name, err)\n        raise HomeAssistantError(\n            f\"Unable to load mfa module {module_name}: {err}\"\n        ) from err\n\n    if hass.config.skip_pip or not hasattr(module, \"REQUIREMENTS\"):\n        return module\n\n    processed = hass.data.get(DATA_REQS)\n    if processed and module_name in processed:\n        return module\n\n    processed = hass.data[DATA_REQS] = set()\n\n    await requirements.async_process_requirements(\n        hass, module_path, module.REQUIREMENTS\n    )\n\n    processed.add(module_name)\n    return module","sourceCodeStart":141,"sourceCodeEnd":177,"githubUrl":"https://github.com/home-assistant/core/blob/58a3fdb3ea0538617f0a07efcfba6294de64fd59/homeassistant/auth/mfa_modules/__init__.py#L141-L177","documentation":"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.","triggerScenarios":"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.","commonSituations":"Hand-edited configuration.yaml after reading outdated docs; version upgrades that rename modules; custom integrations trying to register MFA modules by name only.","solutions":["Fix the key under auth_mfa_modules in configuration.yaml to a real module (e.g. `totp:` or `notify:`)","Check the logged preceding line 'Unable to load mfa module %s: %s' for the exact ImportError reason","Restart Home Assistant after correcting the config"],"exampleFix":"# before (configuration.yaml)\nauth_mfa_modules:\n  - otp:   # no such module\n\n# after\nauth_mfa_modules:\n  - totp:","handlingStrategy":"validation","validationCode":"from homeassistant.auth import mfa_modules\nvalid = set(mfa_modules.MULTI_FACTOR_AUTH_MODULES) | set(getattr(mfa_modules, \"AUTH_MULTI_FACTOR_AUTH_MODULES\", {}))\nconfigured = [m for m in my_config]\nassert set(configured) <= valid","typeGuard":null,"tryCatchPattern":"try:\n    await auth_manager.async_get_auth_mfa_module(module_id)\nexcept HomeAssistantError as err:\n    if not str(err).startswith(\"Unable to load mfa module\"):\n        raise\n    # surface config error to user","preventionTips":["Validate configuration.yaml keys against the shipped module list after upgrades","Run `hass --script check_config` before restart when editing auth_mfa_modules","Watch the log line preceding the exception for the underlying ImportError"],"tags":["auth","python","home-assistant","mfa","config","import-error"],"backgroundTag":null,"analyzedSha":"58a3fdb3ea0538617f0a07efcfba6294de64fd59","analyzedAt":"2026-08-14T20:54:38.818Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}