Backup restore fails with Can't read tarfile seeking backwards is not allowed

[yu-tendo]

Describe the issue you are experiencing

Dear all,

Currently, I try to migrate to the Home Assistant OS. As of now I was hosting the application as a regular service on a virtual machine (Arch Linux + Home Assistant package). While importing my backup, the import fails and home assistant reports the following issue in the Supervisor Protocoll section: Can't read tarfile seeking backwards is not allowed (see attached log file)

I tried to re-create my backup but I always run into this issue. I am not aware of anything special in my current home assistant setup that could cause the issue. I appreciate any hint and support. Please let me know if you need any additional details.

Thank you!

What type of installation are you running?

Home Assistant OS

Which operating system are you running on?

Home Assistant Operating System

Steps to reproduce the issue

1. Create manually backup in my current home assistant instance (Core 2025.10.2) running on Arch Linux
2. Download the tar file and upload it to the home assistant OS instance (Core 2025.10.4)
3. Start the restore procedure (through the web frontend)
4. After 1-2 hours the system is responsive again and nothing changed. The log files state that the restore procedure failed.
   ...

Anything in the Supervisor logs that might be useful for us?

2025-11-03 19:24:04.628 INFO (MainThread) [supervisor.backups.manager] Restore 0be0c7ad starting stage home_assistant
2025-11-03 19:24:04.634 INFO (SyncWorker_7) [supervisor.docker.manager] Stopping homeassistant application
2025-11-03 19:24:12.229 INFO (SyncWorker_7) [supervisor.docker.manager] Cleaning homeassistant application
2025-11-03 21:09:21.637 ERROR (SyncWorker_0) [supervisor.homeassistant.module] Can't read tarfile <securetar.SecureTarFile object at 0x7f13a586c3b0>: seeking backwards is not allowed
2025-11-03 21:09:28.440 ERROR (MainThread) [supervisor.backups.manager] Restore 0be0c7ad error
Traceback (most recent call last):
  File "/usr/src/supervisor/supervisor/homeassistant/module.py", line 478, in _restore_home_assistant
    backup.extractall(
    ~~~~~~~~~~~~~~~~~^
        path=temp_path,
        ^^^^^^^^^^^^^^^
        members=secure_path(backup),
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        filter="fully_trusted",
        ^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/usr/local/lib/python3.13/tarfile.py", line 2355, in extractall
    self._extract_one(tarinfo, path, set_attrs=not tarinfo.isdir(),
    ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                      numeric_owner=numeric_owner,
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                      filter_function=filter_function)
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.13/tarfile.py", line 2458, in _extract_one
    self._extract_member(tarinfo, os.path.join(path, tarinfo.name),
    ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                         set_attrs=set_attrs,
                         ^^^^^^^^^^^^^^^^^^^^
                         numeric_owner=numeric_owner,
                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                         filter_function=filter_function,
                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                         extraction_root=path)
                         ^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.13/tarfile.py", line 2555, in _extract_member
    self.makelink_with_filter(
    ~~~~~~~~~~~~~~~~~~~~~~~~~^
        tarinfo, targetpath,
        ^^^^^^^^^^^^^^^^^^^^
        filter_function=filter_function,
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        extraction_root=extraction_root)
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.13/tarfile.py", line 2689, in makelink_with_filter
    self._extract_member(filtered, targetpath,
    ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
                         filter_function=filter_function,
                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                         extraction_root=extraction_root)
                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.13/tarfile.py", line 2547, in _extract_member
    self.makefile(tarinfo, targetpath)
    ~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.13/tarfile.py", line 2594, in makefile
    source.seek(tarinfo.offset_data)
    ~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.13/tarfile.py", line 521, in seek
    raise StreamError("seeking backwards is not allowed")
tarfile.StreamError: seeking backwards is not allowed
The above exception was the direct cause of the following exception:
Traceback (most recent call last):
  File "/usr/src/supervisor/supervisor/backups/manager.py", line 736, in _do_restore
    task_hass = await backup.restore_homeassistant()
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/src/supervisor/supervisor/jobs/decorator.py", line 307, in wrapper
    raise err
  File "/usr/src/supervisor/supervisor/jobs/decorator.py", line 299, in wrapper
    return await method(obj, *args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/src/supervisor/supervisor/backups/backup.py", line 897, in restore_homeassistant
    await self.sys_homeassistant.restore(
        homeassistant_file, self.homeassistant_exclude_database
    )
  File "/usr/src/supervisor/supervisor/jobs/decorator.py", line 307, in wrapper
    raise err
  File "/usr/src/supervisor/supervisor/jobs/decorator.py", line 299, in wrapper
    return await method(obj, *args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/src/supervisor/supervisor/homeassistant/module.py", line 528, in restore
    data = await self.sys_run_in_executor(_restore_home_assistant)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.13/concurrent/futures/thread.py", line 59, in run
    result = self.fn(*self.args, **self.kwargs)
  File "/usr/src/supervisor/supervisor/homeassistant/module.py", line 484, in _restore_home_assistant
    raise HomeAssistantError(
        f"Can't read tarfile {tar_file}: {err}", _LOGGER.error
    ) from err
supervisor.exceptions.HomeAssistantError: Can't read tarfile <securetar.SecureTarFile object at 0x7f13a586c3b0>: seeking backwards is not allowed

System information

System Information

version	core-2025.10.4
installation_type	Home Assistant OS
dev	false
hassio	true
docker	true
container_arch	amd64
user	root
virtualenv	false
python_version	3.13.7
os_name	Linux
os_version	6.12.43-haos
arch	x86_64
timezone	Europe/Berlin
config_dir	/config

Home Assistant Cloud

logged_in	false
can_reach_cert_server	ok
can_reach_cloud_auth	ok
can_reach_cloud	ok

Home Assistant Supervisor

host_os	Home Assistant OS 16.2
update_channel	stable
supervisor_version	supervisor-2025.10.0
agent_version	1.7.2
docker_version	28.3.3
disk_total	227.6 GB
disk_used	8.3 GB
nameservers	192.168.168.230, 192.168.168.32
healthy	true
supported	true
host_connectivity	true
supervisor_connectivity	true
ntp_synchronized	true
virtualization	kvm
board	ova
supervisor_api	ok
version_api	ok
installed_addons

Dashboards

dashboards	2
resources	0
views	0
mode	storage

Network Configuration

adapters	lo (disabled), enp0s3 (enabled, default, auto), docker0 (disabled), hassio (disabled), vethf436553 (disabled), veth0d71279 (disabled), vethf2e75ec (disabled), vethfe60933 (disabled), vethb4c24f6 (disabled), veth1725b2c (disabled)
ipv4_addresses	lo (127.0.0.1/8), enp0s3 (192.168.168.30/24), docker0 (172.30.232.1/23), hassio (172.30.32.1/23), vethf436553 (), veth0d71279 (), vethf2e75ec (), vethfe60933 (), vethb4c24f6 (), veth1725b2c ()
ipv6_addresses	lo (::1/128), enp0s3 (fe80::398c:566f:3d6f:f262/64), docker0 (fe80::fc95:e1ff:fe52:269c/64), hassio (fd0c:ac1e:2100::1/48, fe80::ec5d:5eff:fed7:97cf/64), vethf436553 (fe80::a07a:4ff:fe74:4565/64), veth0d71279 (fe80::58f0:c0ff:fe17:4f34/64), vethf2e75ec (fe80::bcc2:15ff:fe21:7db0/64), vethfe60933 (fe80::b062:24ff:fe57:966c/64), vethb4c24f6 (fe80::8005:3bff:fe48:f957/64), veth1725b2c (fe80::86a:68ff:fed0:5431/64)
announce_addresses	192.168.168.30, fe80::398c:566f:3d6f:f262

Recorder

oldest_recorder_run	2. November 2025 um 09:56
current_recorder_run	3. November 2025 um 21:09
estimated_db_size	0.46 MiB
database_engine	sqlite
database_version	3.49.2

Supervisor diagnostics

No response

Additional information

No response

[yu-tendo]

I figured out that my issue is actually the following one:
#5891

As a quick workaround, I used Google Gemini to generate a Python script that replaces the hard links within my backup.tar file. After applying this fix, I was able to successfully upload and import the backup.

In my specific case, the majority of the hard links originate from the Python environment, which is located in /var/lib/hass.

--

On a separate, slightly frustrating note: Once the backup was imported, I hit a roadblock where Home Assistant OS failed to start, searching for the (supported) MariaDB which was not part of the backup archive. Because official migration docs for this scenario are missing, my solution was to first migrate my production setup to SQlite. This made the database an official part of the HA backup, and that simple change allowed the Home Assistant OS system to boot successfully!

--

I also run into this issue (There should be really a FAQ for these migration things):
https://community.home-assistant.io/t/unable-to-restore/940680
Thus, if someone runs into the following error:

return hass.data[DATA_NETWORK]
       ~~~~~~~~~^^^^^^^^^^^^^^

KeyError: 'network'

Verify your configuration.yaml file. The issue may be due to missing SSL certificates, as they are not included in the backup file. You will need to manually copy them to your Home Assistant OS system.
(see also here: https://community.home-assistant.io/t/certificate-authority-and-self-signed-certificate-for-ssl-tls/196970)

[amalon]

I figured out that my issue is actually the following one: #5891

As a quick workaround, I used Google Gemini to generate a Python script that replaces the hard links within my backup.tar file. After applying this fix, I was able to successfully upload and import the backup.

In my specific case, the majority of the hard links originate from the Python environment, which is located in /var/lib/hass.

Can you share the script you used? When I manually extract the tar, I get an unreadable (presumably somehow encrypted) tar.gz, even with ha-backup-tool. Searching my /var/lib/hass/ I also get a bunch of hard links in .venv and .cache, so I suspect I'm seeing the same issue.

Its frustrating that i'm being pushed from core to HAOS, yet the ability to migrate to it is so badly broken.

[amalon]

nm, I managed to use hass_unpacker with the previous tag of securetar to extract it, removed .venv & .cache (making it significantly smaller), recreated the tar (tweaking backup.json from the old one), and it seemed to restore okay. Thanks for pointing this out