home-assistant/core · error · BackupManagerError

{err}

Error message

{err}

What it means

Raised by BackupManager.async_create_backup when generating the backup fails with BackupReaderWriterError from the local reader/writer; the message is the reader/writer's own error text (str(err)) re-wrapped as BackupManagerError. This is the filesystem-side failure of actually writing the tar file — most commonly insufficient disk space in the backup directory, but also permission or I/O errors.

Source

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

                self._backup_task,
            ) = await self._reader_writer.async_create_backup(
                agent_ids=available_agents,
                backup_name=backup_name,
                extra_metadata=extra_metadata
                | {
                    "instance_id": await instance_id.async_get(self.hass),
                    "with_automatic_settings": with_automatic_settings,
                },
                include_addons=include_addons,
                include_all_addons=include_all_addons,
                include_database=include_database,
                include_folders=include_folders,
                include_homeassistant=include_homeassistant,
                on_progress=self.async_on_backup_event,
                password=password,
            )
        except BackupReaderWriterError as err:
            raise BackupManagerError(str(err)) from err

        backup_finish_task = self._backup_finish_task = self.hass.async_create_task(
            self._async_finish_backup(
                available_agents, unavailable_agents, with_automatic_settings, password
            ),
            name="backup_manager_finish_backup",
        )
        if not raise_task_error:

            def log_finish_task_error(task: asyncio.Task[None]) -> None:
                if task.done() and not task.cancelled() and (err := task.exception()):
                    if isinstance(err, BackupManagerError):
                        LOGGER.error("Error creating backup: %s", err)
                    else:
                        LOGGER.error("Unexpected error: %s", err, exc_info=err)

            backup_finish_task.add_done_callback(log_finish_task_error)

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Check free space in the backup directory (df -h) and delete or offload old backups, then retry.
2. Verify write permissions on the backup directory and that the underlying filesystem is mounted read-write.
3. Read the embedded reader/writer message for the precise OS error (No space left on device, Read-only file system, Permission denied).
4. Consider excluding large folders or the database, or moving the backup directory to larger storage.

import shutil

usage = shutil.disk_usage(manager.get_backup_path_dir())
if usage.free < estimated_backup_size * 1.2:
    raise RuntimeError(
        f"only {usage.free // 2**20} MiB free; backup will likely fail"
    )

from homeassistant.components.backup.manager import BackupManagerError

try:
    new_backup = await manager.async_create_backup(...)
except BackupManagerError as err:
    if "No space left" in str(err):
        await prune_old_backups()
        new_backup = await manager.async_create_backup(...)
    else:
        raise

When it happens

Trigger: Starting a backup when the volume holding the backup directory is (nearly) full; the backup path is not writable (permissions changed, read-only FS); I/O errors while writing the large tar; the backup directory does not exist or cannot be created.

Common situations: Small HAOS boxes filling their disk with old backups; USB backup drive full/unmounted-ro; container installs where /backups is a small bind mount; permission changes after moving config.

Related errors

• {result}
• At least one available backup agent must be selected, got {a
• Cannot include all addons and specify specific addons
• You need at least Home Assistant version {backup_meta_versio
• Failed during {func.__name__}

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