home-assistant/core · error · ValueError

You need at least Home Assistant version {backup_meta_versio

Error message

You need at least Home Assistant version {backup_meta_version} to restore this backup

What it means

Raised during backup restore when the backup's backup.json metadata records a Home Assistant version newer than the currently running core (compared with AwesomeVersion against HA_VERSION). Restoring would require data/schema features the running instance does not have, so it aborts before extracting homeassistant.tar.

Source

Thrown at homeassistant/backup_restore.py:105

        TemporaryDirectory() as tempdir,
        securetar.SecureTarArchive(
            restore_content.backup_file_path,
            mode="r",
        ) as ostf,
    ):
        ostf.tar.extractall(
            path=Path(tempdir, "extracted"),
            filter="tar",
        )
        backup_meta_file = Path(tempdir, "extracted", "backup.json")
        backup_meta = json.loads(backup_meta_file.read_text(encoding="utf8"))

        if (
            backup_meta_version := AwesomeVersion(
                backup_meta["homeassistant"]["version"]
            )
        ) > HA_VERSION:
            raise ValueError(
                f"You need at least Home Assistant version"
                f" {backup_meta_version} to restore this backup"
            )

        with securetar.SecureTarFile(
            Path(
                tempdir,
                "extracted",
                f"homeassistant.tar{'.gz' if backup_meta['compressed'] else ''}",
            ),
            gzip=backup_meta["compressed"],
            password=restore_content.password,
        ) as istf:
            istf.extractall(
                path=Path(tempdir, "homeassistant"),
                filter="tar",
            )
            if restore_content.restore_homeassistant:

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Upgrade the running Home Assistant core to at least the version printed in the message, then retry the restore
2. If only config (not database) is needed, extract the backup manually (tar + homeassistant.tar.gz) and copy selected YAML/.storage files into the older instance
3. Check the backup's backup.json homeassistant.version to confirm which release created it

from awesomeversion import AwesomeVersion
from homeassistant.const import __version__ as HA_VERSION
import json, tarfile

with tarfile.open("backup.tar") as tar:
    meta = json.load(tar.extractfile("backup.json"))
assert AwesomeVersion(meta["homeassistant"]["version"]) <= AwesomeVersion(HA_VERSION), \
    "backup too new — upgrade core first"

def backup_is_restorable(meta: dict, running_version: str) -> bool:
    return AwesomeVersion(meta["homeassistant"]["version"]) <= AwesomeVersion(running_version)

try:
    restore_backup(...)
except ValueError as ex:
    if "version" in str(ex):
        # upgrade core, then retry the same backup

When it happens

Trigger: Restoring a backup created on a newer Home Assistant release (e.g. backup from 2025.6 restored onto 2024.12); the check runs in the restore reader right after extracting backup.json from the outer tar.

Common situations: Downgrading after an upgrade gone wrong, migrating a backup from a newer dev/staged instance, or restoring a backup made on a different channel (e.g. beta) into an older stable install.

Related errors

• Failed during {func.__name__}
• Failed to upload backup
• Backup {backup_id} not found
• Backup integration is not available
• Backup {backup_id} not found

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