Unraid cache corruption errors: preserve data and find the cause

Steps to follow

1. Capture the exact error and storage layout

   Save diagnostics before restarting, then record the pool name, device serial numbers, filesystem and redundancy profile. Distinguish an unmountable filesystem, checksum error, read-only mount, I/O error and a damaged application file. They are not interchangeable symptoms. Include the time of the first warning and any preceding power failure, hardware change or software update.

   Check whether appdata, system files, virtual-machine disks or a downloads share live on this pool. Do not assume that a path called cache contains only disposable temporary files. Also identify files waiting for Mover. Their presence in a normal network share can disguise the fact that the only current copy is still on the affected pool.

2. Reduce writes and preserve accessible information

   Stop applications that are continuously changing the affected storage, using their normal shutdown controls where possible. Copy the most important readable files to a healthy, separate destination. Prioritise unique documents, application exports and recent uploads over replaceable downloads. A recovery copy should not be stored on another folder within the same failing pool.

   For databases, prefer an application-supported export when the service remains healthy enough to create one; otherwise preserve the available state without improvising an invasive repair. Record copy errors rather than repeatedly hammering an unreadable file. If devices are disappearing or the data is irreplaceable, specialist recovery advice may be safer than additional scans.

3. Choose diagnostics for the actual filesystem

   For Btrfs, examine device errors and the appropriate scrub guidance; a scrub can verify checksums and may repair damage where a valid redundant copy exists. It cannot manufacture a missing good copy on a single-device pool. Avoid treating btrfs check --repair as a routine fix. It is a specialist recovery operation, not a first diagnostic command.

   For ZFS, inspect pool status and follow its scrub or recovery workflow. For XFS, follow the documented offline filesystem-check procedure for the correct device. These tools have different mounting requirements and repair behaviour. Do not paste an array-disk command into a pool incident merely because both paths contain a disk number. Identify the target and consult the installed version's instructions first.

4. Diagnose hardware and validate a recovery route

   Review device health information alongside the system log. Connection resets, rising transport errors, power problems, overheating and memory instability can all deserve investigation. A clean overall SMART status does not prove that every part of the storage path is healthy. Check changes over time and correlate them with the error timestamps.

   After the cause is understood, decide whether repair, restoration to healthy storage or device replacement offers the clearest recovery path. Preserve the original devices until the recovered copy has been checked. Bring applications back individually and test their actual records or libraries. Seeing a container start or a share mount is only an initial check, not proof that its data is complete.

Detailed guidance

Pool redundancy and array parity protect different things

A mirrored pool can tolerate some device failures, but it remains separate from the Unraid parity array. A single SSD pool is not protected just because the array has two parity disks. Check the pool's actual data and metadata profile rather than inferring protection from the number of drives visible in the chassis.

Suppose yesterday's media files reached the array but today's photographs and a service database remain on the pool. Array parity can help with an array-disk failure; it does not recover those pool-only files. Your backup selection therefore needs to include persistent pool data explicitly, with a restore method appropriate to each application.

Do not confuse a disposable image with persistent app data

A Docker image can sometimes be recreated when container definitions and persistent data remain intact, but that is a different diagnosis from pool corruption. Deleting an image before preserving evidence can remove useful context without fixing the underlying filesystem. Identify precisely which file is damaged and where each container keeps its database, uploads and settings.

Treat virtual-machine disks with similar care. A VM that boots after a storage incident can still contain damaged guest files. Check the guest's own logs and important data after the host storage is stable. If restoration is needed, choose a backup point and test it in isolation before replacing the only current machine state.

Evidence of improvement should be repeatable

Record the initial error counters and the checks performed. Clearing counters can make a screen look clean while concealing whether a problem is recurring. Compare later observations with the original record after ordinary workloads resume. If errors return on a replacement drive using the same cable or controller, the shared path needs further attention.

Finish with a recovery rehearsal for one representative item: restore an older file or application record to a separate location and open it. Schedule appropriate health monitoring and backup checks, avoiding overlapping heavy jobs while you establish stability. The aim is a pool whose contents and recovery route are understood, not merely a warning banner that has disappeared.

Compare the options

Frequently asked questions

Related guides

• Set Up Immich on Unraid: Choose One Deployment and Protect App Data
• Best PC for After Effects in the UK: RAM, GPU and Cache
• The 3-2-1 Backup Rule: Build a Plan You Can Restore