Troubleshooting

This page is organised by what you see during an Unraid migration. Find your symptom, check the likely causes, then follow the fix. The scan, review, import and verify steps only read from your disks, so you can stop at any of them and take your time. Before step 17, going back is clean: see Rollback.

Unraid is a trademark of Lime Technology, Inc.; Hoserva is not affiliated with it.

A disk is not detected

The scan lists each disk in Unraid's configuration and looks for it on this machine by serial number. A disk it cannot find is flagged with a message that starts "Unraid had a disk with serial" and ends "Attach it before the import."

Likely causes:

• The disk is not connected or powered, or you left it disconnected after installing Debian.
• A USB enclosure hides the disk's serial number, so it cannot be matched.

To fix it:

1. Shut down, reconnect or reseat the disk, and start again.
2. Scan again. If the disk shows up, carry on.
3. If the disk is gone, do not go on until you understand why. A missing data disk means its files are missing.

A disk is refused

A disk marked Blocked is not adopted, and the report says why. The scan goes on with the other disks, but a refused data disk makes the verdict No-go until you resolve it. The common reasons are:

What the report says	What it means	What to do
The disk is encrypted	Encrypted (LUKS) disks are never adopted.	Decrypt the disk in Unraid first, or leave it out of the migration.
The disk is a ZFS disk	Hoserva cannot read ZFS.	Leave it out of the migration, or convert it to a supported filesystem in Unraid first.
The disk is one of several devices of a btrfs filesystem	It is not a self-contained filesystem per disk.	Same as above.
The flash names a filesystem Hoserva does not adopt, or the device holds one	Only XFS, ext4 and single-device btrfs are adopted.	Convert or leave out the disk.
The flash says one filesystem and the device says another	Hoserva does not guess which is right.	Check the disk in Unraid, then scan again.
The device reports no filesystem, no filesystem node or no UUID	There is nothing to adopt or mount by.	Check the disk is the one you expect, then scan again.
The disk's filesystem UUID is also on another disk	Two disks with one UUID cannot both be adopted.	Resolve the duplicate in Unraid, then scan again.
The disk is reported failed	This machine reports the disk as failed, so it is not adopted.	Stop the migration. Check the disk's cabling first. If the disk is dying, replace it in Unraid and let Unraid rebuild its files from parity, or copy its files off, then scan again. Do not leave a data disk out: its files would be lost when step 17 erases Unraid's parity.
The filesystem could not be shown to be single-device or clean (btrfs), or its journal could not be shown clean (ext4)	Hoserva could not confirm the disk is safe to mount, and it does not guess.	Check the disk in Unraid, stop the array cleanly, then scan again.
The disk passed its checks but could not be read completely	The baseline read of its files failed part way, for example on a read error.	Check the disk's cabling and SMART health in Unraid, then scan again. If it fails again, stop the migration: replace the disk in Unraid and let Unraid rebuild its files from parity, or copy its files off, then scan again. Do not leave a data disk out: its files would be lost when step 17 erases Unraid's parity.
The log was not unmounted cleanly	The disk was not stopped cleanly. Hoserva never replays a log on a disk it does not own yet.	Start Unraid, stop the array cleanly and scan again.
The read-only filesystem check failed	The filesystem has damage. Computing parity over it would keep the damage.	Repair it in Unraid, then scan again.
The disk is Unraid's boot device, or the disk this machine boots from	These are never given a data or parity role.	Set its role to Ignore.
The parity disk has only a weak identity	A USB enclosure hides its serial number, and a parity disk needs one.	Connect it directly, or use another disk as parity.

Other findings can also block the migration. More than two parity disks, or a parity disk smaller than the largest data disk, is Blocked. A disk with reallocated or pending sectors is Flagged with a recommendation to abort, because the unprotected window is when a marginal disk fails.

The scan refuses my zip

The scan reads the zip in memory and refuses what it does not recognise. Likely causes:

• The Unraid version is outside 6.12.x and 7.x, or the zip does not state a version. Check that it is the Flash Backup from Before you start, whose root is /boot.
• The zip has no usable config/disk.cfg. It is not a complete flash backup.
• The zip is larger than 2 GiB. A real Flash Backup is a few hundred MiB, so check that it is the right file.

To scan a version or layout Hoserva has not been verified against, add --unverified-layout to hoserva migrate scan. The web UI has no such option. The override is recorded in the report, and you should check every row of it before you rely on it.

A share is empty or missing after the import

Until the point of no return, the shares are directories inside the read-only pool at /mnt/user. Likely causes:

• The share's files lived only on the cache. They are not on the adopted data disks. The report flags such a share: "no directory on any matched data disk".
• A data disk was refused, so what it holds is not in the pool. See A disk is refused.
• The share is an orphan. Its configuration exists but no disk holds a directory for it, so it is reported and not imported.
• Its name was refused. A share whose name Hoserva does not accept, such as one with a space, is not created and never renamed, because a rename would break every container path and SMB mapping that uses it. The report flags it as not carried over.
• It is a hidden folder. A top-level folder such as .Trash-1000 is not a share.

Do not initialise parity with files still on the cache

If a share's files lived only on the cache, they are not adopted, and the cache is formatted at step 17. Stop before step 17.

To fix it:

1. Do not go past the verify.
2. Run hoserva migrate undo-import --yes, then boot Unraid again (see Rollback).
3. Move the share to the array, empty the cache as in step 5 of Before you start, run the prepare script again and migrate from the start.

For a refused name, rename the share in Unraid and update the container paths that use it before you scan again.

A container cannot find its appdata

hoserva migrate containers check <name> reports each folder a container uses under /mnt/user or /mnt/cache as ok, empty, missing or unreadable. A container whose folder is empty or missing starts with no data, or fails.

Likely causes:

• Appdata is still on the array. You emptied the cache in step 5, so a template that points at /mnt/cache/appdata finds nothing until step 18 moves appdata back.
• The template points at another named pool. One Unraid pool maps to /mnt/cache. Paths into other /mnt/<pool> names are flagged when the template is converted.
• The share is empty, for one of the reasons in the previous section.
• The container kept its state inside itself. That state, in Docker's own storage, is not carried over.

To fix it:

1. Read the check output to see which path is empty or missing.
2. If appdata is on the array and you have a cache, run hoserva share relocate appdata --to cache.
3. If the path is wrong, save the stack's Compose file with hoserva stack show <name> > compose.yml, correct the path, and apply it with hoserva stack edit <name> --file compose.yml.
4. Start the stack with hoserva migrate containers start <name>, then run check again.

If a folder is meant to be empty, hoserva migrate containers confirm <name> --accept-failed-check accepts it.

Permissions are wrong

At step 17, Hoserva sets each share's top-level directory on every disk it uses to mode 2775 and group ID 100. It does not recurse, so no file's ownership is rewritten. A client or container that cannot write to a share may be hitting a top-level directory that differs. The scan's App user ID row also flags it when user ID 99 is already taken on this machine.

1. Check the directory with ls -ldn /mnt/user/<share>. The mode should read drwxrwsr-x and the group should be 100.
2. As root, correct that one directory with chmod 2775 and chgrp 100.
3. Do not run a recursive chown or chmod over a share. It rewrites the ownership of every file and touches every disk the share spans.

Initialise parity is refused or not offered

The point of no return is offered only after a verify that passed. When it is refused, nothing has been erased. Likely causes:

• There is no passing verify. The message reads "the adopted array has no passing verify". Run the verify and fix what it reports. An import after the verify forgets its result, so a re-import needs a new verify.
• There is no import waiting. The data disks have to be imported first.
• A recorded disk is gone, was swapped or changed. The message reads "the disks are not the ones the adoption recorded", or the page names the problem. Reconnect the original disk.
• No data disk has enough free space. The message reads "the pool could not create the share directories the migration needs". Make room on a data disk in Unraid or undo the import, then import again.
• The cache is a partition of an Unraid boot device that may be one of a mirrored pair. Hoserva never formats it. Choose another cache, or none.
• The confirmation does not match. It has to be exactly the string shown, because it names every device that will be erased.

Initialising parity stopped with an error

The web UI shows The initialisation did not finish with the reason, and hoserva jobs shows the job as failed. What to do depends on how far the run got. Read the job's log with hoserva logs --job <id>, then check which of these you are in with hoserva migrate status.

The run stopped before the formatted disks were recorded. This covers a failure while formatting the first disk, while formatting a later one, or while recording them. Hoserva mounts your data disks read-only again, so the migration goes back to the verified state. The web UI offers Initialise parity again, and the command line asks for the full ERASE confirmation again. Any former parity or cache device that was already formatted has lost its old contents, so going back to Unraid still means restoring from a backup. Running it again formats the former parity and cache devices again. A data disk is never formatted, in either run. To go on:

1. Read the reason the run gave and fix it. A disk that was unplugged or changed is the usual cause.
2. If you cannot tell what happened, or the log says the data disks could not be mounted read-only again, stop and run hoserva migrate status before you do anything else.
3. Check that the devices in the confirmation are the ones you expect, then run Initialise parity again.

The run stopped after the formatted disks were recorded. The migration is then unfinished but safe to complete. The web UI offers Finish initialisation and the command line prints the confirmation to type back with --confirm. Both mount the data disks read-write, set up the rest and queue the first sync, and erase nothing. Select it again if it fails again, and read the reason it gives.

The verify does not pass

Any difference fails the verify, and so does a file or folder it cannot read. Stop and investigate: do not initialise parity.

1. Read what differs. The result lists files that are missing, have a different size or content, or are not in the scan, per disk and share. A path that exists on two disks is shown once and is not counted as missing or extra.
2. If the cause is something you fixed, such as a reconnected disk, run the verify again.
3. If files changed after the scan, undo the import with hoserva migrate undo-import --yes, scan again, import and verify.
4. If data is missing or damaged, do not go on. Go back to Unraid as described in Rollback.

Next steps

• The migration
• Rollback
• After the migration