Roon Server on QNAP Docker not recognizing backup for restore (ref#QUG2T9)

Sevenfeet · May 6, 2026, 7:34pm

Hi! What’s not quite right with Roon?

· None of the above quite fits

None of the above quite fits

· None of these quite match

Tell us what's going on

· In setting up Roon Server on a QNAP Docker, the app works but
I cannot get Roon to see the old backups so I can do a proper
restore. I just copied the latest backup directory to the place
where Roon Server can see it, but it doesn't seem to understand.
Any ideas?

Tell us about your home network

· Unifi UDM Pro Max, Unifi Enterprise 24 and Aggregation Switches, other smaller switches throughout the house.

noris · May 7, 2026, 11:50pm

Hey @Sevenfeet, thanks for reaching out. Could you share what your Docker YAML file looked like, and confirm whether Roon Server was installed to the correct directory per the Installing RoonServer on QNAP with Docker instructions?

Sevenfeet · May 8, 2026, 2:32am

This is the YAML

services:
roonserver:
image: Package roonserver · GitHub
container_name: roonserver
network_mode: host
environment:

ROON_INSTALL_BRANCH=production
TZ=America/Chicago
volumes:
/share/Container/roon:/Roon
/share/Music:/Music
/share/Container/roon-backups:/RoonBackups
restart: unless-stopped
logging:
driver: local

Yes, I used the instructions link and the Docker container works….I just can’t do a restore since it can’t find the old folder or where I copy it to for it to find it.

Arindal · May 8, 2026, 6:45am

Did you find in File Station the old folder where you pointed roon at when performing a backup?

What happens if you, using file station, copy that whole folder into:
Container/roon-backups

Sevenfeet · May 8, 2026, 8:17pm

Sevenfeet · May 8, 2026, 8:19pm

Enclosed is a screen shot of FileStation 5 with my container shared folder and Roon-backups folder shown. The folder inside is the last backup that the old .qpkg version completed before the transition. I had copied it to this folder.

benjamin · May 12, 2026, 5:53pm

Hey @Sevenfeet,

Thanks for writing in and for sharing your report! From a fresh Roon Server diagnostic report, we can see that every time Roon tries to enumerate backups from /RoonBackups, it throws a Critical NullReferenceException inside GetRestoreItems:

Critical: scx: System.NullReferenceException: Object reference not set to an instance of an object.
 at RoonBackup.Backups.GetRestoreItems(...)

This happens consistently; it’s not a transient error. Roon can see the /RoonBackups mount (it lists it in the file browser), but when it tries to actually read the backup structure inside it, the code crashes immediately.

Some additional thoughts on this:

Roon’s backup format is very specific. It doesn’t just look for “a folder.” It expects this exact nested structure:

/RoonBackups/
 └── /
 └── /
 ├── backup.json ← REQUIRED
 └── ... (other backup files)

What you currently have in FileStation is:

/RoonBackups/
 └── 084f10e3-0fb2-ba7d-faf3-0701931e2888/ ← just one folder

The NullReferenceException in GetRestoreItems is almost certainly triggered because backup.json is missing or the subfolder hierarchy is wrong. Roon reads backup.json to understand the backup set, and if it can’t find it, the object it tries to use is null.

Open that GUID folder in FileStation and look inside. You should see another GUID subfolder, and inside that, a backup.json file plus files like RoonServer.roonbackup or similar.
If the folder contents look like just a bare copy of files without that backup.json, the backup copy may be incomplete or from an incompatible format (e.g., copied from a QNAP backup app rather than Roon's native backup).
If your old Roon install (the .qpkg version) saved backups to a different path, make sure you're copying the right folder — the one Roon itself created, not a system-level backup of the QPKG data directory.

With that, we also see both /Roon and /RoonBackups are mapped to the same ZFS Dataset

The logs show something unusual:

/RoonBackups → zpool1/zfs26
/Roon → zpool1/zfs26 ← SAME dataset!

Both volumes are backed by the same ZFS dataset. This is almost certainly a misconfiguration, they should be separate. It’s possible the QNAP Container Station volume mapping is conflating them. This could cause subtle filesystem behavior that confuses Roon’s backup scanner, though it’s secondary to the structure issue above.

What to do: In your Docker Compose, confirm the host paths are genuinely different on your NAS — /share/Container/roon vs /share/Container/roon-backups should be separate folders on the filesystem.

I’d confirm the ZFS dataset split In QNAP Storage Manager, verify that /share/Container/roon and /share/Container/roon-backups are actually separate shared folders, not the same one with a subfolder alias.

Then, restart the container and try the restore again. After fixing the structure, restart the roonserver container, then in the Roon app go to Settings → Backups → Restore and browse to /RoonBackups.

Let me know if any of the above help!

Sevenfeet · May 18, 2026, 2:22am

Sorry for taking so long to respond to this.

I’m going to try to explain some of how my system is setup. Some of what you see are just stuff I’ve added in recent weeks. But let’s start with the original 2.64 setup. I’ve not upgraded the old RoonOnNAS .qpkg setup so it still works. Backup for this version of Roon is at:

/share/RoonServer/RoonBackups (this is the same as /share/ZFS25_DATA/RoonServer/RoonBackups)

The RoonBackups folder looks like this:

drwxrwxrwx 5 admin administrators 7 2026-05-16 02:00 ./

drwxrwxrwx 9 admin administrators 10 2026-04-17 14:10 ../

drwxrwxrwx 259 admin administrators 261 2026-05-16 02:00 084f10e3-0fb2-ba7d-faf3-0701931e2888/

drwxrwxrwx 259 admin administrators 261 2026-03-17 02:00 264992a8-f298-ee98-2f74-f2fa58435477/

drwxrwxrwx 259 admin administrators 262 2023-11-08 02:00 56002e28-fb74-5c29-2bf3-e932fb489639/

-rwxrwxrwx 1 rewing everyone 6148 2023-08-23 19:57 .DS_Store*

-rwxrwxrwx 1 admin administrators 19 2026-05-16 02:00 _roon_backup_root_*

In this folder and in the folders created by Roon for backup of the database, including the most recent one dated 5-16-2026, I do not see a file called backup.json. Also, QSirch 7.02 cannot find it either anywhere on my NAS.

As for /Roon and /RoonBackups, I am a bit puzzled by saying that /Roon and /Roonbackups are on the same dataset. They are on the same ZFS shared folder but ZFS26 is the main Container shared folder for all containers.

[rewing@ewingnas Container]$ ls -al

total 90

drwxrwxrwx 10 admin administrators 11 2026-04-28 21:11 ./

drwxr-xr-x 3 admin administrators 4 2022-05-08 23:22 ../

drwxrwxrwx 8 admin administrators 8 2022-12-15 18:13 container-station-data/

drwxrwxrwx 3 admin administrators 4 2022-12-23 10:40 dashy/

-rwxrwxrwx 1 rewing everyone 14340 2026-05-08 09:57 .DS_Store*

drwxrwxrwx 7 admin administrators 16 2023-04-08 08:46 homeassistant/

drwxrwxrwx 6 rewing everyone 15 2025-06-28 22:27 homebridge/

drwxr-xr-x 3 admin administrators 3 2022-12-21 21:34 portainer-ce/

drwxrwxrwx 2 admin administrators 23 2026-05-15 21:27 @Recently-Snapshot/

drwxr-xr-x 5 admin administrators 6 2026-05-07 21:23 roon/

drwxr-xr-x 3 admin administrators 3 2026-05-08 06:54 roon-backups/

[rewing@ewingnas Container]$ pwd

/share/ZFS26_DATA/Container

[rewing@ewingnas Container]$

alex_h · May 19, 2026, 9:24pm

@Sevenfeet,

Thanks for the detailed breakdown and the terminal output!.

This clears things up immensely and points us right to the solution.

First, you are completely right about the ZFS datasets. Having both your roon and roon-backups directories under your main /share/ZFS26_DATA/Container/ shared folder is standard practice for Docker setups.

Your storage configuration is fine.

Looking at your directory listings, we’ve found the exact culprit. In your old backup directory, there is a specific file called roon_backup_root. This file is the crucial marker that tells Roon, “this directory is the root of a valid backup location.”
In the FileStation screenshot you shared earlier, it looks like you only copied the inner GUID folder (084f10e3-0fb2-ba7d-faf3-0701931e2888) into your new /share/Container/roon-backups directory, leaving roon_backup_root and the other folders behind. Without that root marker file, Roon doesn’t recognize the directory as a backup destination, which triggers the NullReferenceException when it tries to scan it.
Here is the fix:

Stop your roonserver Docker container.
Empty the current contents of your /share/Container/roon-backups/ directory.
Copy the entire contents of your old /share/RoonServer/RoonBackups/ directory (most importantly the _roon_backup_root_ file, plus all the GUID folders) directly into /share/Container/roon-backups/.
Start the container again.

Once that is done, go to Settings → Backups → Find backups in the Roon app, browse to your mapped /RoonBackups folder, and your previous backups should immediately populate for a restore. Let us know how it goes!

Sevenfeet · May 20, 2026, 11:40pm

Success! Your instructions were spot on and I am back up and running. One note…the Storage folders do not map directly from what they were in the old .qpkg app. You are offered a link to edit the folder to the new mapping which is fairly straightforward. Once all my folders were remapped (and didn’t need to do a full rescan), everything seems to now be working perfectly. So thank you again for getting me through this.

Sevenfeet · May 21, 2026, 11:56am

One other bit of errata…..I did have to logout and log back into Tidal, which something gets confused during transitions.