home-assistant/core · warning · BackupNotFound

Backup {backup_id} not found

Error message

Backup {backup_id} not found

What it means

Raised as BackupNotFound(f'Backup {backup_id} not found') by S3BackupAgent._find_backup_by_id when the requested backup_id is not present in the (possibly cached) listing of backups in the S3 bucket. Home Assistant's backup manager uses this to know the agent cannot serve that backup for download or delete.

Source

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

        return list(backups.values())

    @handle_boto_errors
    @override
    async def async_get_backup(
        self,
        backup_id: str,
        **kwargs: Any,
    ) -> AgentBackup:
        """Return a backup."""
        return await self._find_backup_by_id(backup_id)

    async def _find_backup_by_id(self, backup_id: str) -> AgentBackup:
        """Find a backup by its backup ID."""
        backups = await self._list_backups()
        if backup := backups.get(backup_id):
            return backup

        raise BackupNotFound(f"Backup {backup_id} not found")

    async def _list_backups(self) -> dict[str, AgentBackup]:
        """List backups, using a cache if possible."""
        if time() <= self._cache_expiration:
            return self._backup_cache

        backups_list = await async_list_backups_from_s3(
            self._client, self._bucket, self._prefix
        )
        self._backup_cache = {b.backup_id: b for b in backups_list}
        self._cache_expiration = time() + CACHE_TTL

        return self._backup_cache

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Confirm the backup still exists in S3 under the configured bucket and prefix (aws s3 ls or console).
2. If the prefix/bucket changed, re-point the config entry or move objects back under the expected prefix.
3. Check bucket lifecycle/expiration rules aren't deleting backups.
4. Note the listing may be cached for CACHE_TTL seconds — re-check after the cache expires.

backups = await agent._list_backups()
if backup_id not in backups:
    skip_local_delete(backup_id)  # avoid BackupNotFound on delete/download

async def backup_exists(agent, backup_id: str) -> bool:
    backups = await agent._list_backups()
    return backup_id in backups

from homeassistant.components.backup import BackupNotFound

try:
    await agent.async_get_backup(backup_id)
except BackupNotFound:
    # treat as already removed; safe to skip in delete/download flows
    pass

When it happens

Trigger: Calling async_get_backup or delete with a backup_id that is not a key in _list_backups(): backup was deleted from S3 directly, the prefix/bucket in the config entry changed, the listing cache predates a remote deletion, or the metadata object for that backup is missing/corrupt.

Common situations: User manually cleaned the S3 bucket; config entry's prefix changed so old backups are no longer listed; bucket lifecycle rules expired objects; cache TTL (CACHE_TTL) masking a very recent external deletion.

Related errors

• Failed during {func.__name__}
• Failed to upload backup
• invalid_credentials
• invalid_bucket_name
• invalid_endpoint_url

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