What causes "Failed to upload backup" in home-assistant/core?

Inspect logs for the chained BotoCoreError to identify whether it is auth, permission, or connectivity.

home-assistant/core · error · BackupAgentError

Failed to upload backup

Error message

Failed to upload backup

What it means

Raised as BackupAgentError('Failed to upload backup') inside S3BackupAgent's upload path when either the simple upload, the multipart upload, or the metadata put_object raises BotoCoreError. It aborts the backup upload and surfaces an error to the backup workflow; the cache reset only happens on success.

Source

Thrown at homeassistant/components/aws_s3/backup.py:163

        :param backup: Metadata about the backup that should be uploaded.
        """
        tar_filename, metadata_filename = suggested_filenames(backup)

        try:
            if backup.size < MULTIPART_MIN_PART_SIZE_BYTES:
                await self._upload_simple(tar_filename, open_stream)
            else:
                await self._upload_multipart(tar_filename, open_stream, on_progress)

            # Upload the metadata file
            metadata_content = json.dumps(backup.as_dict())
            await self._client.put_object(
                Bucket=self._bucket,
                Key=self._with_prefix(metadata_filename),
                Body=metadata_content,
            )
        except BotoCoreError as err:
            raise BackupAgentError("Failed to upload backup") from err
        else:
            # Reset cache after successful upload
            self._cache_expiration = time()

    async def _upload_simple(
        self,
        tar_filename: str,
        open_stream: Callable[[], Coroutine[Any, Any, AsyncIterator[bytes]]],
    ) -> None:
        """Upload a small file using simple upload.

        :param tar_filename: The target filename for the backup.
        :param open_stream: A function returning an async iterator that yields bytes.
        """
        _LOGGER.debug("Starting simple upload for %s", tar_filename)
        stream = await open_stream()
        file_data = bytearray()
        async for chunk in stream:

View on GitHub (pinned to 58a3fdb3ea)

Solutions

Inspect logs for the chained BotoCoreError to identify whether it is auth, permission, or connectivity.
Verify s3:PutObject permission and that the bucket still accepts writes (aws s3 cp a test file).
For flaky uplinks, reduce backup size or fix network stability; multipart uploads must complete every part.
Re-run the backup after the root cause is fixed; partial multipart uploads may need abort-cleanup on the bucket to reclaim storage.

Defensive patterns

Strategy: retry

Try / catch

from homeassistant.components.backup import BackupAgentError

for attempt in range(2):
    try:
        await agent.async_upload_backup(path, backup, on_progress)
        break
    except BackupAgentError as err:
        if attempt == 1:
            alert(f"upload failed: {err.__cause__}")
            raise

Prevention

Ensure long-lived credentials (non-expiring IAM keys) for multi-hour uploads.
Stabilize the uplink for large multipart backups; each part must complete.
Periodically abort orphaned multipart uploads on the bucket to avoid silent storage growth.

When it happens

Trigger: put_object / create_multipart_upload / upload_part / complete_multipart_upload fails mid-upload: expired credentials mid-way, network drop during a long multipart transfer, bucket policy now denies PutObject, or multipart abort leftovers.

Common situations: Large backups over unstable uplinks (multipart part fails); temporary IAM credentials expiring during multi-hour uploads; bucket changed to deny writes; endpoint (MinIO) restarted during upload.

Related errors

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