{"record":{"id":"c8ab853e1c32fd36","repo":"home-assistant/core","slug":"failed-to-upload-backup","errorCode":null,"errorMessage":"Failed to upload backup","messagePattern":"Failed to upload backup","errorType":"exception","errorClass":"BackupAgentError","httpStatus":null,"severity":"error","filePath":"homeassistant/components/aws_s3/backup.py","lineNumber":163,"sourceCode":"        :param backup: Metadata about the backup that should be uploaded.\n        \"\"\"\n        tar_filename, metadata_filename = suggested_filenames(backup)\n\n        try:\n            if backup.size < MULTIPART_MIN_PART_SIZE_BYTES:\n                await self._upload_simple(tar_filename, open_stream)\n            else:\n                await self._upload_multipart(tar_filename, open_stream, on_progress)\n\n            # Upload the metadata file\n            metadata_content = json.dumps(backup.as_dict())\n            await self._client.put_object(\n                Bucket=self._bucket,\n                Key=self._with_prefix(metadata_filename),\n                Body=metadata_content,\n            )\n        except BotoCoreError as err:\n            raise BackupAgentError(\"Failed to upload backup\") from err\n        else:\n            # Reset cache after successful upload\n            self._cache_expiration = time()\n\n    async def _upload_simple(\n        self,\n        tar_filename: str,\n        open_stream: Callable[[], Coroutine[Any, Any, AsyncIterator[bytes]]],\n    ) -> None:\n        \"\"\"Upload a small file using simple upload.\n\n        :param tar_filename: The target filename for the backup.\n        :param open_stream: A function returning an async iterator that yields bytes.\n        \"\"\"\n        _LOGGER.debug(\"Starting simple upload for %s\", tar_filename)\n        stream = await open_stream()\n        file_data = bytearray()\n        async for chunk in stream:","sourceCodeStart":145,"sourceCodeEnd":181,"githubUrl":"https://github.com/home-assistant/core/blob/58a3fdb3ea0538617f0a07efcfba6294de64fd59/homeassistant/components/aws_s3/backup.py#L145-L181","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"from homeassistant.components.backup import BackupAgentError\n\nfor attempt in range(2):\n    try:\n        await agent.async_upload_backup(path, backup, on_progress)\n        break\n    except BackupAgentError as err:\n        if attempt == 1:\n            alert(f\"upload failed: {err.__cause__}\")\n            raise","preventionTips":["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."],"tags":["home-assistant","aws","s3","backup","upload","multipart"],"backgroundTag":null,"analyzedSha":"58a3fdb3ea0538617f0a07efcfba6294de64fd59","analyzedAt":"2026-08-14T20:54:38.818Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}