Home Assistant: Ultimate Restore Guide

Sometimes you have the need to build a new Home Assistant installation and restore your old configuration. Maybe your SD card died, or you want to migrate Home Assistant to a more powerful server. In fact, you can even do cross-platform migrations (e.g. from a Raspberry Pi 4 to a Proxmox VM on an Intel processor) seamlessly. That’s pretty cool.

Home Assistant has a built-in backup and restore functionality, but it’s not super polished. So you might run into issues or headaches so this post attempts to cover various restore options and some lessons learned.

This post focuses on Home Assistant OS (HAOS), which is a fully managed solution for Home Assistant. This is different from Supervised (you provide your own OS), container, and other options. Those solutions would have a different restore workflow.

Backup Options

As mention in my Home Assistant: Getting Started Guide implementing remote backups for Home Assistant is critical. Without any add-ons, Home Assistant snapshots are just stored locally. If your storage media dies (and your Raspberry Pi SD card WILL at some point), then you are out of luck. For that reason, I strongly urge doing remote backups. IMHO, the best option is the Google Drive add-on. This is a robust tool which, shockingly, backups your HA configuration to Google Drive for safe keeping. You can setup complex scheduling and rotation schemes.

Restoring Home Assistant

Whether you are migrating your existing Home Assistant to a new server (or VM), or your old server died, the process is the same for HAOS. The first thing thing you need to do is get a copy of your last backup on your local computer. If you are using the Google drive add-on and your old HA server died, just browse to your Google drive and find the latest copy and download it. If your old HAOS server is up, you can directly download the last backup from within the Google Drive add-on UI in HA. It is VERY important to note how large the backup is.

If your backup is UNDER 1GB, then life is easier for you. If your backup is OVER 1GB, additional steps are required. I will cover both scenarios, starting with the easy one….under 1GB.

Restoring a Backup Under 1GB

If your backup archive is under 1GB in size, you are in luck. The process should be pretty quick and easy. Let’s walk through the process:

Re-install a fresh copy of Home Assistant OS. If you want to install HAOS on Proxmox, follow my Proxmox Quick Start Guide.
Wait for the install to complete and STOP on the on-boarding screen.

3. At the bottom of the on-boarding screen click on the Alternatively you can restore from a previous backup option.

4. Locate your locally downloaded backup file. Select Full backup and enter your backup password if you used one. Click on RESTORE. Acknowledge the warning and click RESTORE.

5. At this point the Home Assistant UI fails us. There is ZERO feedback on if the restore is working, if it failed, or had errors. And you have no idea when it is done. Huge fail. In fact, after you click Restore the last time, the screen just sits at the on-boarding window and it appears nothing happened. Pretty unacceptable, IMHO.

Tip: If you are restoring HAOS on Promox, once the restore starts, flip to the VM Summary screen and monitor CPU, network and disk activity. After things quiet down, proceed. My backup was 62MB and restored in less than 5 minutes on an Intel i5-1235U mini-pc.

6. Refresh your web browser and see if you get a regular Home Assistant login box (image below). If not, the restore is not yet complete or it failed. Wait a few minutes and try again.

Tip: If your production HA was using SSL certificates, then before you refresh your browser change the URL to use HTTPS. If you don’t do this you’ll be sitting there all day refreshing even if the restore is complete.

7. Important: Now that you are at the login screen, login, and then do a full HAOS reboot (NOT restart). Wait for your system to reboot, then skip down to the Post Restore Checks section below.

8. If you are running HAOS in a VM and have any USB passthrough devices, then shutdown the HAOS VM and re-attach any USB devices.

Tip: If your restore is failing or giving you troubles from the ‘fresh’ welcome screen, then:

1. Re-install HAOS from scratch
2. Login to the fresh install with dummy information and do a restore from the bare bones HA UI (not on the welcome screen). The steps are in the next section, but you can skip the SAMBA install since your backup is under 1GB.

Restoring a Backup Over 1GB

If your backup archive is OVER 1GB in size, we have extra work to do. We will need to install an add-on, like Samba share, to upload the large backup file to HAOS, then do a restore. You don’t have to use Samba, but it is quick and easy. Other options include FTP. Let’s walk through the Samba process:

Re-install a fresh copy of Home Assistant OS. If you want to install HAOS on Proxmox, follow my Proxmox Quick Start Guide.
Wait for the install to complete and use your browser to navigate to the IP address of the new HAOS instance.
Complete all the on-boarding screens using throw-away information. Our restore will over-write everything you input here.
When you get to the Home Assistant main landing page UI, click on Settings -> Add-ons -> ADD-ON STORE.
Search for Samba and click on Samba share.

6. Click on INSTALL.
7. Before you click start, click on Configuration at the top.
8. Enter a password and click on save.
9.Click on the Info tab and click START.
10. Connect to the Samba share from your PC or Mac. On a Mac you can open Safari and in the URL type smb://IP and open it in Finder.
11. For the username use homeassistant and the password you configured.
12. Navigate to the backup volume.
13. Upload your backup file into the Samba folder.
14. Navigate to Settings -> System -> Backups.
15. You should see the back that you just uploaded.
16. Click on the backup, select full backup, and enter your backup password (if any). Click on RESTORE, acknowledge the warning, and click on RESTORE again.

17. At this point the Home Assistant UI fails us. There is ZERO feedback on if the restore is working, if it failed, or had errors. And you have no idea when it is done. Huge fail. In fact, after you click Restore the last time, the screen just sits at the on-boarding window and it appears nothing happened. Pretty unacceptable, IMHO.

18. Refresh your web browser and see if you get a regular Home Assistant login box. If not, the restore is not yet complete or it failed. Wait a few minutes and try again.

19. Important: Now that you are at the login screen, login, and do a full HAOS reboot (NOT restart). Wait for your system to reboot, then skip down to the Post Restore Checks section below.

20. If you are running HAOS in a VM and have any USB passthrough devices, then shutdown the HAOS VM and re-attach any USB devices.

Post Restore Checks

Unfortunately even if you get the login prompt and your old credentials work, there can be silent failures of some add-ons. So we need to review the logs to spot any issues.

Login to HA. Make sure Advanced mode is turned on.
Navigate to Settings -> System -> Logs and select Supervisor in the upper right corner.
Review the logs for any errors or warnings.
Change to the Home Assistant Core logs and review them as well.
Navigate to Settings -> Devices & Services and check the health of all integrations.
Perform check on various devices and automations to confirm everything appears to be working.

Note: If any of your add-ons appear broken, we can do a partial restore to see if we can recover them. See the next section.

Partial Restore Procedure

If any of your add-ons appear broken, Home Assistant has a built-in partial restore feature. This lets us selectively restore add-ons.

Navigate to Settings -> System -> Backups.
Click on your backup.
Select Partial backup.
Tick the box next to any add-ons that are failing and that you want to restore.
Enter your restore password (if any) and proceed with the restore.
After the restore is done, do a full HAOS reboot (NOT restart).

Hopefully at this point your add-on is now in a working state. If not, review the logs and try to further troubleshoot.

Summary

Home Assistant could really use some love in the backup/restore department. Specifically, doing a restore is very mysterious with zero feedback in the UI on any progress. Plus, you can still have silent add-on failures that are only visible in logs. And if your backup is over 1GB, that has even more challenges. So ya, the Home Assistant restore process need a lot of work. But, it DOES usually work, even if it is a bit mysterious. I hope this post helps you have a smoother Home Assistant restore process.