Unraid / Troubleshooting
Unraid Array Will Not Start
Match the exact Main Array Operation message first, then separate missing disks, device-limit, license, key-server, and withdrawn-release branches before any array, disk, or license change.
The official array-health documentation gives this diagnosis its central rule: when the array will not start, identify the problem from the error message under Main, Array Operation. It then documents one exact message per branch — missing disks, attached-device limits, invalid or missing keys, key-server contact, and withdrawn releases — so the whole tree keys off matching the observed message first.[1]
The same documentation defines the parity arithmetic the missing-disk branch depends on: with one parity drive only one disk may be missing, with two parity drives two disks may be missing, and parity protects only until a replacement disk arrives. It also warns that the New Config procedure, the Parity is Valid checkbox, and disk formatting all sit on the destructive side of array operations and are never diagnostic experiments.[1][2]
Applicability
- Products
- Unraid OS
- Scope
- For Unraid OS 7.x stable where pressing Start, or booting, leaves the array stopped with an error under Main, Array Operation. Trial licenses need key-server contact at boot while paid licenses do not; withdrawn beta or release-candidate builds are a separate documented branch. This page does not cover a started but degraded array, parity-check error interpretation on a running array, single-disk rebuild procedures, pool-only issues, or Docker and VM failures with a healthy array.[1]
- Last verified
Symptoms
- The Unraid array stays stopped after pressing Start or after boot, with an error message under Main, Array Operation, and array-dependent shares and services stay offline. A started array with failed or degraded disks, or services failing while the array runs, is a different observation.[1]
Quick diagnosis
Match the exact Main Array Operation message first, then count missing disks against parity before any array, disk, or license change.
Record the exact Array Operation message
Read the message under Main, Array Operation word for word, including which disks it names and any license or key-server wording. The documented branches are message-specific: too many wrong or missing disks, too many attached devices, an invalid or missing key, key-server contact failure, and withdrawn release each select a different path. Do not paraphrase the message from memory.[1]
Record disk assignments, parity count, and license state
Record which slots hold parity and data disks, how many disks report missing or wrong, the license tier and whether it is trial or paid, and the boot device identity. The missing-disk branch needs the missing count against the parity count; the device-limit branch needs the attached-device count against the tier limit.[1]
Do not reset, format, override parity validity, or change assignments before classification
Do not run New Config, check Parity is Valid, format any disk, or assign or unassign disks before the exact message is matched and the missing-versus-parity arithmetic is done. The official documentation warns that resetting configuration, overriding parity validity without certainty, and formatting all destroy protection or data, and that New Config clears the history a rebuild would need.[1][2]
Interactive troubleshooter
Your answers stay in this browser tab. The tool does not connect to your systems or send diagnostic results.
Guided check / step 1
Safe diagnostic guidanceDoes the array stay stopped with an error under Main Array Operation?
Confirm the array will not start and an error message is shown under Main, Array Operation. A started array with degraded disks, or services failing while the array runs, is a different observation.[1]
Read the complete diagnostic tree without using the controls
- Does the array stay stopped with an error under Main Array Operation?
Confirm the array will not start and an error message is shown under Main, Array Operation. A started array with degraded disks, or services failing while the array runs, is a different observation.[1]
- Yes, stopped array with a message → Which exact documented message is shown?
- No, a different observation → Investigate the actual array observation
- Which exact documented message is shown?
Match the observed message word for word against the documented messages. Each message selects its own branch; an unmatched message exits to evidence preservation rather than to a guessed fix.[1]
- Too many wrong and/or missing disks → Does the missing count stay within the parity count?
- Too many attached devices → Reduce attached devices to the tier limit
- Invalid or missing registration key → Install, renew, or replace the registration key
- Cannot contact key-server → Restore key-server reachability and revalidate
- Release has been withdrawn → Install the latest stable and restart
- Different or unclear message → Collect an array start evidence packet
- Does the missing count stay within the parity count?
Count wrong or missing disks against assigned parity disks: one parity drive tolerates one missing disk, two tolerate two. Within tolerance the documented path is disk replacement; beyond tolerance the data cannot be parity-protected and only the high-impact boundary remains.[1]
- Yes, within parity tolerance → Replace the missing disk
- No, beyond parity tolerance → Beyond parity tolerance: high-impact boundary only
- Cannot confirm the counts → Collect an array start evidence packet
- Replace the missing disk
Replace the missing disk, one at a time for dual-parity configurations, then start the array so the rebuild runs. Check drive health reports before starting the rebuild.[1]
- Reduce attached devices to the tier limit
Stop the array, remove unneeded storage devices until the attached count fits the license tier (the boot USB is excluded), start the array, and only then reconnect devices for non-array use.[1]
- Install, renew, or replace the registration key
Obtain the correct trial or paid key and install it through the Registration screen, or move to a compatible replacement boot device for a blacklisted GUID. Paid licenses need no key-server step afterwards.[1]
- Restore key-server reachability and revalidate
On a trial boot, restore network reachability to the key server and let validation re-attempt through WebGUI refresh or navigation. Key replacement is not the fix for a reachability failure.[1]
- Install the latest stable and restart
Install the latest stable version through Tools, Update OS, then restart the server so the array can start. This branch applies only to withdrawn beta or release-candidate builds.[1]
- Beyond parity tolerance: high-impact boundary only
The data cannot be parity-protected on this branch. No reset, parity-validity override, format, or assignment change happens here: those actions require explicit operator confirmation, preserved assignments, independent backups, and the documented recovery paths described in the high-impact boundary.[1]
- Investigate the actual array observation
A started array with degraded disks needs disk-failure investigation. Parity-check errors on a running array need check-history and SMART investigation. Service failures with a healthy array need service-level investigation.[1]
- Collect an array start evidence packet
Preserve the exact Array Operation message, the disk assignments with parity count, the license tier and key state, the boot device identity, and the installed release. Send the sanitized evidence to the operator; no documented branch remains.[1]
Detailed diagnosis
1. Match the exact documented message
Compare the recorded Array Operation message against the five documented messages: too many wrong and/or missing disks, too many attached devices, invalid or missing registration key, cannot contact key-server, and withdrawn release. An unmatched or unclear message exits to evidence preservation rather than to a guessed branch.[1]
2. Count missing disks against parity disks
For the missing-disk message, count wrong or missing disks and compare with the parity count: one parity drive tolerates one missing disk, two parity drives tolerate two. Within tolerance the documented path is disk replacement; beyond tolerance the array cannot protect the data and the high-impact boundary applies.[1]
3. Scope license, tier, boot device, and release state
For license-worded messages, establish whether the license is trial or paid, whether the attached-device count exceeds the tier limit (the Starter tier limits attached storage devices, excluding the boot USB), whether the boot USB may carry a blacklisted non-unique GUID, and whether the installed release is a withdrawn beta or release candidate rather than stable.[1]
4. For trial boots, separate key-server reachability from key validity
Trial licenses validate against the key server at boot and fail to start the array when contact fails within the window, while paid licenses start without that step. A cannot-contact-key-server message on a trial boot therefore points at reachability and retry behavior, documented as re-attempting on WebGUI refresh or navigation, not at key replacement.[1]
Supported scenarios
These observations narrow the next investigation; they do not establish a unique cause.
More disks are missing or wrong than parity can cover, or a disk needs replacement
The documented missing-disk message appears with the parity arithmetic behind it: one parity drive covers one missing disk and two cover two. Within tolerance the documented path is replacing the missing disk; beyond tolerance the data cannot be protected by parity.[1]
How to check: Confirm the exact message names missing or wrong disks, then count them against the assigned parity disks before any replacement or reset decision.[1]
Attached storage devices exceed the license tier limit
The documented device-limit message appears when more storage devices are attached than the registration key allows, with the Starter tier carrying a six-device limit that excludes the boot USB. The documented resolution removes unneeded devices before starting.[1]
How to check: Confirm the exact message and count attached storage devices against the tier limit, excluding the boot USB, before removing anything.[1]
The registration key is invalid, missing, expired, or bound to a blacklisted boot device
The documented license branch covers an invalid or missing key, an expired trial, and USB boot devices whose non-unique GUID cannot register a key. Each has its own documented handling through the Registration screen or a compatible replacement device.[1]
How to check: Confirm the exact message and distinguish an expired trial, a missing key, and a blacklisted boot GUID before installing, renewing, or replacing anything.[1]
A trial boot cannot contact the license key server
Trial licenses require key-server contact at boot and the array will not start when contact fails within the window; paid licenses do not take this step. The documentation describes validation re-attempting on WebGUI refresh or navigation after a successful check.[1]
How to check: Confirm the license is a trial and the message is the key-server contact failure, then confirm network reachability to the key server before retrying validation.[1]
The installed release was withdrawn and is not enabled for regular use
The documented withdrawn-release message means a beta or release-candidate build is installed. The documented resolution installs the latest stable version through Tools, Update OS, followed by a restart.[1]
How to check: Confirm the exact message and confirm the installed build is a withdrawn beta or release candidate rather than a stable release.[1]
Next actions and procedure boundaries
Missing disks within parity tolerance: replace the disk
Replace the missing disk, one at a time for dual-parity configurations, then start the array so the documented rebuild path runs. This branch applies only when the missing count stays within the parity count established during classification.[1]
Before changing anything
- Risk
- Disk replacement puts the array through a rebuild that stresses every remaining drive for hours; a second failure during a single-parity rebuild cannot be recovered. Confirm the correct physical disk before touching the array.[1]
- Safer check
- Confirm the exact missing-disk message, the missing count against the parity count, and the identity of the physical disk to replace. Check drive health reports before starting the rebuild.[1]
- Expected result
- After replacement, the array starts and the rebuild completes with the data reconstructed; the array remains usable but slower until the rebuild finishes.[1]
- Backup / recovery access
- Preserve irreplaceable data from the array through an independent backup before the rebuild where possible, and record the full pre-replacement disk assignments.[1]
- Rollback
- There is no rollback for a started rebuild: a failed rebuild leaves the array in the state the documentation describes for the parity count in use. If the rebuild cannot complete, preserve the evidence and seek operator recovery before any reset or format step.[1]
Device-limit message: reduce attached devices to the tier limit
Stop the array, remove unneeded storage devices until the attached count fits the license tier, start the array, and only then reconnect devices for non-array use. The documented limit applies before starting; the boot USB is excluded from the count.[1]
Before changing anything
- Risk
- Disconnecting the wrong device can create a missing-device or start-failure condition and break array availability. Confirm device identity, tier math, and the current disk assignments before disconnecting anything.[1]
- Safer check
- Confirm the exact device-limit message, count attached storage devices excluding the boot USB, and identify which devices are unneeded for the array.[1]
- Expected result
- After removal, the attached count fits the tier and the array starts; removed devices can be reconnected afterwards for non-array use.[1]
- Backup / recovery access
- Record the full pre-change disk assignments so every device can be returned to its slot.[1]
- Rollback
- Restore the recorded prior assignments if the array does not start, then re-collect the Array Operation message before further changes.[1]
License or key-server message: install, renew, or revalidate the key
For an invalid, missing, or expired key, follow the documented Registration path to obtain and install the correct trial or paid key. For a trial key-server contact failure, restore network reachability and let validation re-attempt through WebGUI refresh or navigation. For a blacklisted boot GUID, the documented guidance is to move to a compatible replacement device — a blacklisted device cannot be used anymore.[1]
Before changing anything
- Risk
- License and boot-device changes gate the entire array. A wrong key, or a device change on top of an unclassified message, can compound the outage instead of clearing it.[1]
- Safer check
- Confirm the exact message and distinguish expired trial, missing key, key-server reachability, and blacklisted GUID before changing anything. Record the current key state and boot device identity.[1]
- Expected result
- After the correction, validation succeeds and the array starts; trial validation succeeds once and is not required again until reboot.[1]
- Backup / recovery access
- Record the prior key state, boot device identity, license tier, and, for a key-server reachability fix, the prior network configuration.[1]
- Rollback
- Rollback is branch-specific, not universal. For a key-server reachability fix, restore the prior network configuration. For an invalid, missing, or expired key, correct it through the documented Registration path; there is no generic restore. For a blacklisted boot GUID there is no rollback to the prior device because that device cannot be used anymore — recovery is only the documented compatible-replacement-device guidance.[1]
Withdrawn release: install the latest stable and restart
For the documented withdrawn-release message, install the latest stable version through Tools, Update OS, then restart the server to start the array. This branch applies only to withdrawn beta or release-candidate builds.[1]
Before changing anything
- Risk
- An OS update followed by a restart interrupts every service on the server. Confirm the installed build is actually withdrawn before updating.[1]
- Safer check
- Confirm the exact withdrawn-release message and the installed build identity. Record the current release and disk assignments before updating.[1]
- Expected result
- After the update and restart, the stable release boots and the array starts.[1]
- Backup / recovery access
- Preserve irreplaceable data through an independent backup where possible, and record the prior release and disk assignments.[1]
- Rollback
- If the update does not resolve the start failure, preserve the evidence and seek operator recovery; do not compound the change with a reset or format step.[1]
Before any New Config, parity-validity override, format, or assignment change
Planning boundary only. Resetting the array configuration, checking Parity is Valid without certainty, formatting a disk, or changing disk assignments can destroy data or parity protection: removing a data drive invalidates parity unless it was zeroed, changing disk order can invalidate second parity, New Config clears the history a rebuild would need, and formatting erases the disk while the array runs unprotected until the parity sync finishes. These actions require explicit operator confirmation after the read-only classification, a preserved record of current assignments, independent backups where possible, and whichever documented recovery applies — including renaming super.old back to super.dat and rebooting to undo a reset. Formatting is never a way to fix an inaccessible disk without proof that formatting is actually required.[1][2]
Before changing anything
- Risk
- These actions can cause permanent, unrecoverable data loss: formatting erases the disk, an incorrect Parity is Valid confirmation corrupts protection silently, and a reset removes the rebuild history. Never take them as diagnostic experiments.[1][2]
- Safer check
- Complete the exact-message classification first and confirm no documented non-destructive branch applies. Record full disk assignments, parity state, and license state, and confirm the operator explicitly accepts the data-loss risk.[1]
- Expected result
- A later owner-approved action must leave the intended data protected or explicitly accepted as lost; a started array alone does not prove no data was destroyed.[1]
- Backup / recovery access
- Back up irreplaceable data independently where possible and preserve the full assignment and configuration state before any high-impact action.[1][2]
- Rollback
- Formatting and confirmed data destruction have no rollback: recovery depends entirely on the independent backups taken beforehand. A configuration reset can be undone only through the documented super.old to super.dat rename followed by a reboot, and only where that recovery is officially confirmed for the situation.[1]
If the message matches no documented branch: preserve the evidence
Record the exact Array Operation message, the disk assignments with parity count, the license tier and key state, the boot device identity, and the installed release. Send the sanitized evidence to the operator; the official references describe no procedure for an unmatched start failure.[1]
Warnings and boundaries
Sources
Links were reviewed on 2026-09-07. Reachability and automated validation do not replace editorial verification of each claim.
- Array health and maintenance
Unraid · Tier A · accessed 2026-09-07 - Configure your array
Unraid · Tier A · accessed 2026-09-07