home-assistant/core · error · BackupReaderWriterError

Addons and folders are not supported by core backup

Error message

Addons and folders are not supported by core backup

What it means

BackupReaderWriterError raised by the core backup reader/writer when a backup creation request includes addons, all addons, or folders. Plain Home Assistant Core (no Supervisor/add-ons) cannot back up add-ons or share folders, so these flags are only valid on supervised/HAOS-style backups handled elsewhere.

Source

Thrown at homeassistant/components/backup/manager.py:1735

        self,
        *,
        agent_ids: list[str],
        backup_name: str,
        extra_metadata: dict[str, bool | str],
        include_addons: list[str] | None,
        include_all_addons: bool,
        include_database: bool,
        include_folders: list[Folder] | None,
        include_homeassistant: bool,
        on_progress: Callable[[CreateBackupEvent], None],
        password: str | None,
    ) -> tuple[NewBackup, asyncio.Task[WrittenBackup]]:
        """Initiate generating a backup."""
        date_str = dt_util.now().isoformat()
        backup_id = _generate_backup_id(date_str, backup_name)

        if include_addons or include_all_addons or include_folders:
            raise BackupReaderWriterError(
                "Addons and folders are not supported by core backup"
            )
        if not include_homeassistant:
            raise BackupReaderWriterError("Home Assistant must be included in backup")

        backup_task = self._hass.async_create_task(
            self._async_create_backup(
                agent_ids=agent_ids,
                backup_id=backup_id,
                backup_name=backup_name,
                extra_metadata=extra_metadata,
                include_database=include_database,
                date_str=date_str,
                on_progress=on_progress,
                password=password,
            ),
            name="backup_manager_create_backup",
            eager_start=False,  # To ensure the task is not started before we return

View on GitHub (pinned to 58a3fdb3ea)

Solutions

  1. Set include_addons/include_all_addons to False and include_folders to None/[] when running on HA Core
  2. If you need addon/folder backups, run Home Assistant OS or Supervised instead of Core
  3. Gate the request on what the instance supports (hass.components / supervisor availability) before sending it

Example fix

// before
{"include_addons": ["core_ssh"], "include_folders": ["media"], ...}
// after
{"include_addons": false, "include_folders": null, "include_homeassistant": true, ...}
Defensive patterns

Strategy: validation

Validate before calling

# client-side: only add these flags on supervised installs
payload = {"include_homeassistant": True}
if "hassio" in hass.config.components:
    payload["include_folders"] = folders
# never send include_addons/all_addons/folders to a Core install

Try / catch

try:
    await core_writer.async_create_backup(...)
except BackupReaderWriterError as err:
    if "not supported by core backup" in str(err):
        # strip addon/folder flags and rebuild the request
        ...

Prevention

When it happens

Trigger: Calling the core backup create path (_async_init_create_backup / the core backup websocket API) with include_addons=True, include_all_addons=True, or a non-empty include_folders list.

Common situations: A client or script written for a Supervised install is run against HA Core in a container/venv; UI or API payload copied from a HAOS setup; an integration builds a create-backup request with addon flags unconditionally.

Related errors

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