home-assistant/core · error · BackupManagerError

{result}

Error message

{result}

What it means

Raised while syncing a newly generated backup to agents: if any agent's upload raises BackupReaderWriterError, the manager immediately aborts the whole sync by raising BackupManagerError(str(result)). BackupReaderWriterError comes from the local reader/writer side (the thing that reads the backup file from disk and streams it to agents), so its failure affects every agent — e.g., the backup file vanished or could not be read mid-upload.

Source

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

                    manager_state=self.state,
                    agent_id=agent_id,
                    uploaded_bytes=_backup.size,
                    total_bytes=_backup.size,
                )
            )
            if streamer:
                await streamer.wait()

        sync_backup_results = await asyncio.gather(
            *(upload_backup_to_agent(agent_id) for agent_id in agent_ids),
            return_exceptions=True,
        )
        for idx, result in enumerate(sync_backup_results):
            agent_id = agent_ids[idx]
            if isinstance(result, BackupReaderWriterError):
                # writer errors will affect all agents
                # no point in continuing
                raise BackupManagerError(str(result)) from result
            if isinstance(result, BackupAgentError):
                agent_errors[agent_id] = result
                LOGGER.error("Upload failed for %s: %s", agent_id, result)
                continue
            if isinstance(result, Exception):
                # trap bugs from agents
                agent_errors[agent_id] = result
                LOGGER.error(
                    "Unexpected error for %s: %s", agent_id, result, exc_info=result
                )
                continue
            if isinstance(result, BaseException):
                raise result

        return agent_errors

    async def async_get_backups(
        self,

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Check that the backup file still exists in the backup directory and the disk/filesystem is healthy (df, dmesg for I/O errors).
2. Ensure nothing (cleanup automations, scripts) deletes from the backup directory during the upload window.
3. Free disk space if the volume is full; retry the backup afterwards.
4. Look at the agent upload log lines ('Upload failed for ...') just before the raise for the underlying reader/writer detail.

backup_path = manager.get_backup_path(backup_id)
exists, free = await asyncio.gather(
    hass.async_add_executor_job(backup_path.exists),
    hass.async_add_executor_job(shutil.disk_usage, backup_path.anchor),
)
if not exists or free.free < expected_size:
    LOGGER.warning("aborting sync: file missing or disk low")

from homeassistant.components.backup.manager import BackupManagerError

try:
    await finish_task
except BackupManagerError as err:
    LOGGER.error("agent sync failed (reader/writer): %s", err)
    await verify_backup_file_intact()

When it happens

Trigger: During _async_finish_backup upload phase: the local backup file was deleted, moved, or became unreadable while uploads were streaming; disk I/O error on the backup directory; the reader failed to open/seek the tar file for one of the agents.

Common situations: Backup directory on flaky external storage; an automation or user deleting the fresh backup file while it is still uploading; disk full or filesystem errors during a large backup upload.

Related errors

• Failed to upload backup
• Upload timed out after {UPLOAD_TIMEOUT} seconds
• Backup manager busy: {self.state}
• Invalid filename: {suggested_filename}
• {err}

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