Skip to main content

Changing the flash device

The USB flash device is critical to your Unraid server as it stores the operating system, configuration files, and license. If this device fails or becomes unreliable, prompt replacement is essential to avoid data loss and minimize downtime.

caution

When you replace your Unraid USB flash device, your license is transferred to the new device, and the old flash device is blacklisted and can no longer be used with Unraid. This action is permanent and cannot be undone.

Some common indicators that your USB flash device may need to be replaced include:

  • The server will not boot, or files are missing from the device.
  • The device repeatedly enters read-only mode or shows file system errors.
  • The device is lost or stolen.
  • Storage capacity is insufficient for updates or configuration changes.
  • The physical size of the device does not fit your server setup.

Selecting a replacement device​

When choosing a new USB flash drive for Unraid, focus on reliability and compatibility over speed.

Requirements

RequirementDetails
USB versionUSB 2.0 recommended (typically more reliable and widely compatible than USB 3.0)
Unique GUIDMust contain a unique hardware GUID in programmable ROM
Minimum sizeAt least 4 GB
Maximum recommended size32 GB (for ease of manual installs; larger devices may work but are not necessary)
Brand/vendorPurchase from reputable brands and trusted retailers; avoid second-hand or gray-market
Physical sizeChoose a form factor that fits your server’s available USB ports and physical constraints

For more guidance on selecting the best flash device for Unraid, check out Spaceinvader One's video guide on USB flash drive testing.

Rules of thumb for replacement

  • Buy USB drives from reputable retailers and avoid auction sites and unknown sellers.

  • Avoid second-hand or previously used drives.

  • Test the new drive on your server before transferring your license.

  • Be cautious of counterfeit products, even from well-known brands.

    note

    The forum announcement on counterfeit SanDisk drives from January 2022 confirms SanDisk is not recommended due to counterfeit devices and manufacturing changes resulting in non-unique GUIDs. This affects both counterfeit and legitimate SanDisk drives.

Replacing your USB flash device​

Before you replace

Before replacing your current flash device, consider checking it for errors:

  1. Shut down your server and remove the flash device.
  2. Insert the device into a Windows or Mac computer.
  3. Use Windows Scandisk or Mac Disk Utility to check for and repair errors.
  4. If errors are found and repaired, you may continue using the device. If issues persist or recur, replacement is recommended.

A single power outage or incomplete write can sometimes cause minor corruption, which is usually repairable. However, repeated issues signal the need for a new device.

There are two ways to replace your Unraid USB flash device: the recommended USB flash creator tool for Windows or macOS, or the manual method for advanced users. Always back up your flash device before starting.

Backing up your flash device​

  1. Go to the Main tab and select your flash device.
  2. Under Flash device settings, click FLASH BACKUP to download a zipped backup to your computer.

Flash Backup

Alternatively, use Unraid Connect for automated flash backups, but be aware, sensitive data like passwords and WireGuard keys are excluded from cloud backups, while Docker templates with potentially sensitive information are included.

What if I can't back up my device? - Click to expand/collapse

If your flash device has failed and no backup is available:

  1. Prepare a new flash device using the USB flash creator or manual method.
  2. Copy your old license key file (if available) into the boot/config directory on the new device.
  3. Assign your disks to the array/cache exactly as before. Keep a screenshot of your disk assignments for reference.
  4. If you’re unsure about disk assignments, ask for help in the Unraid forums before starting the array.
Backup best practices
  • Regularly back up your flash device, especially after major configuration changes.
  • Store backups off-server (on another computer or cloud storage).
  • Keep a screenshot of your disk assignments after any hardware changes.
Trial keys and device changes

If you transfer a trial configuration to a new flash device, you will not be able to start the array until you purchase a valid registration key. Trial keys only work on the original device.

Replacement methods​

Recommended for most users

  1. Download the Unraid USB flash creator tool for Windows or macOS.
  2. Insert your new USB flash device into your computer.
  3. In the creator tool, click the Operating System, scroll down to Use custom and browse to your backup ZIP file.

Select version

  1. Choose your new USB flash device as the destination and click Write.
  2. Shut down your server, replace the old flash device with the new one, and power on.
  3. When prompted with Invalid, missing or expired registration key, select Registration key.

Invalid Key

  1. If needed, copy your existing license key file into boot/config on the new device.
  2. Ensure only one key file exists in the config folder.
  3. In Tools → Registration, select Replace key and enter your email address.

Invalid Key

  1. Follow the instructions in the email to install your new key.
  2. Once complete, select Done.
important

If you see a "keyfile is not valid" error, your key may be blacklisted or not the last valid key. Contact Unraid support for assistance.

You have now replaced your USB flash device and transferred your Unraid registration key. The system will display the registration date and the next eligible replacement date.

Registration key replacement frequency​

Replacing your Unraid registration key is straightforward, but there are important details about timing and eligibility to keep in mind.

  • You can replace your registration key at any time. However, after the first replacement, you must wait 12 months before using the automated online method again.
  • If you need to replace your key again within 12 months, contact Unraid support. For faster service, include your old and new USB GUIDs, your license key, and the email address used for purchase.
important

If you're locked out due to exceeding the automated replacement limit and need immediate server access, set up a new Unraid trial with a new USB drive, then contact support to transfer your license.

Recovering from a failed flash device without a backup​

Losing your flash device and not knowing your disk assignments can be stressful, but you can avoid data loss by taking careful steps.

caution

Never assign a data disk as a parity drive. Incorrect assignments can overwrite data with parity information, resulting in permanent data loss.

Identifying drives
  • Parity drives do not have a mountable file system. If a drive cannot be mounted, it is likely a parity drive.
  • Data drives previously used by Unraid retain their data even after resetting the array configuration.
  • If you find more unmountable drives than expected parity drives, stop and seek help in the Unraid forums.

To safely reconfigure your array:

  1. Prepare a fresh Unraid flash drive, following the instructions provided earlier in this guide.
  2. Edit /boot/config/disk.cfg and set startArray="no" to prevent the array from starting automatically.
    • Alternatively, you can use Settings → Disk Settings in the GUI to disable auto-start.
  3. Navigate to Tools → New Config to create a new array configuration.
    • Assign all drives as data drives and start the array.
    • Note the serial numbers of drives that do not mount; these are likely your parity drives.
    • You can also use the Unassigned Devices plugin to test-mount each drive, identifying parity by elimination.
  4. Go to Tools → New Config again and create a new array configuration, retaining all the currently configured drives.
  5. Assign the correct drives as parity and the rest as data drives in the Main tab.
  6. If you have a single parity drive, the order of data drives is not critical - check Parity is Valid. For dual parity, both the order of the data drives and the assignment of parity1 and parity2 are important. Parity1 and parity2 are not interchangeable, and parity must be rebuilt.
  7. Start the array to commit assignments. Data drives should mount, and their contents should remain intact.
  8. If you checked Parity is Valid, run a correcting parity check to confirm that your configuration is correct.
note

After restoring your array, verify any share-specific include/exclude settings, as the order of data drives may have changed.

* "WireGuard" and the "WireGuard" logo are registered trademarks of Jason A. Donenfeld.