home-assistant/core · error · BackupManagerExceptionGroup

Multiple errors when creating backup: {unhandled_exc}, {err}

Error message

Multiple errors when creating backup: {unhandled_exc}, {err}

What it means

BackupManagerExceptionGroup raised when the backup creation already failed with an unhandled exception AND the subsequent async_post_backup_actions() also raised. HA wraps both exceptions in an ExceptionGroup so neither is silently lost; the message embeds both exception reprs.

Source

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

                release_stream=remove_backup,
            )
        finally:
            # Inform integrations the backup is done
            # If there's an unhandled exception, we keep it so we can rethrow it in case
            # the post backup actions also fail.
            unhandled_exc = sys.exception()
            try:
                try:
                    await manager.async_post_backup_actions()
                except BackupManagerError as err:
                    raise BackupReaderWriterError(str(err)) from err
            except Exception as err:
                if not unhandled_exc:
                    raise
                # If there's an unhandled exception, we wrap both that and the exception
                # from the post backup actions in an ExceptionGroup so the caller is
                # aware of both exceptions.
                raise BackupManagerExceptionGroup(
                    f"Multiple errors when creating backup: {unhandled_exc}, {err}",
                    [unhandled_exc, err],
                ) from None

    def _mkdir_and_generate_backup_contents(
        self,
        backup_data: dict[str, Any],
        database_included: bool,
        password: str | None,
        tar_file_path: Path | None,
    ) -> tuple[Path, int]:
        """Generate backup contents and return the size."""
        if not tar_file_path:
            tar_file_path = self.temp_backup_dir / f"{backup_data['slug']}.tar"
        try:
            make_backup_dir(tar_file_path.parent)
        except OSError as err:
            raise BackupReaderWriterError(

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Inspect the ExceptionGroup's .exceptions — fix the primary (unhandled) exception first, the secondary usually shares the root cause
2. Check disk space and permissions on the backup/temp directories
3. If a custom agent raises in both upload and post-backup hooks, make its post-backup handler idempotent and non-raising on failure
4. Retry the backup after fixing the root cause

Example fix

# before
try:
    await manager.async_create_backup(...)
except BackupManagerExceptionGroup as eg:
    raise  # opaque
# after
try:
    await manager.async_create_backup(...)
except BackupManagerExceptionGroup as eg:
    for exc in eg.exceptions:
        _LOGGER.error("Backup failure: %r", exc)
    raise

try:
    await manager.async_create_backup(...)
except* BackupManagerExceptionGroup as eg:
    for exc in eg.exceptions:
        _LOGGER.error("backup failure: %r", exc)
    # handle primary (write) failure; secondary is usually collateral

When it happens

Trigger: An exception is active in the current task (sys.exception() is set, e.g. inside an except* block of the create flow) while cleanup/post-backup actions (e.g. notifying agents the backup finished) raise another exception.

Common situations: Backup write fails (disk full, agent upload error) and the post-backup hook (agent bookkeeping, event firing) also fails — commonly the same underlying network/disk issue hits both stages; misbehaving custom backup agent raising in both write and finalize callbacks.

Related errors

• You need at least Home Assistant version {backup_meta_versio
• Failed during {func.__name__}
• Failed to upload backup
• Backup {backup_id} not found
• Backup integration is not available

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