Hi all,

I’m running several automated Python scripts on Unraid via cron, and recently started seeing the following error in the logs they generate:

[Errno 117] Structure needs cleaning

I ran the Fix Common Problems plugin and noticed warnings indicating that some of my disks are still formatted as ReiserFS, which is deprecated and slated for removal from the Linux kernel in 2025, with a recommendation to convert to XFS.

Before assuming the filesystem is the root cause, I wanted to better understand what typically triggers an Errno 117 on Unraid and whether this points to filesystem corruption, disk issues, or something else I should validate first.

I do plan to migrate the ReiserFS disks to XFS, but I’d like to confirm the underlying issue and the recommended next steps before making changes.

I’ve attached my diagnostics file. Any guidance on how to properly identify and correct the cause would be greatly appreciated.

Thanks in advance for any help.

tower-diagnostics-20251227-1324.zip

Where do you see those errors logged? Don't see any in the syslog, also not seeing any apparent fs issues.

Hi All,

Put my logs in Chatgpt, asked it the same question above, and I was able to fix the issue. I'll paste the reply here in case it helps anyone:

How to fix [Errno 117] Structure needs cleaning (Unraid-safe steps)

1) Identify which disk or path is triggering the error

This error is surfaced by the application or process that first touches the affected filesystem, but the root cause is filesystem corruption, not the application itself.

To identify the impacted disk:

• If the error references a path like:

  • /mnt/diskX/... → the affected disk is known

  • /mnt/user/... (user share) → the data may reside on multiple disks

If the disk is not obvious from the path, check:

• Tools → System Log

• Search for keywords such as:

  • EUCLEAN

  • Structure needs cleaning

  • mdX

  • XFS, BTRFS, or reiserfs

In many cases, the kernel log will explicitly reference the affected device (for example, md6), often at the time the error first occurred.

---

2) Check disk health and cabling (quick sanity check)

Before attempting filesystem repair, verify that the disk is not actively failing.

• Go to Main → click the disk → SMART report

• Look for:

  • Reallocated sectors

  • Pending sectors

  • Read errors

  • UDMA CRC errors (often indicate a bad or loose SATA cable)

If CRC errors are present or increasing, reseat or replace the SATA cable before or after running filesystem repair.

---

3) Run the correct filesystem repair in Maintenance Mode

On Unraid, [Errno 117] Structure needs cleaning almost always indicates filesystem metadata corruption and requires a filesystem check/repair.

Recommended steps:

1. Stop the array

2. Start the array in Maintenance Mode

3. Click the affected disk on the Main tab

4. Run the filesystem check/repair appropriate for the disk format

---

If the disk is XFS (most common on Unraid arrays)

Run a dry run first:

xfs_repair -n /dev/mdX

If issues are reported, run the actual repair:

xfs_repair /dev/mdX

If the repair cannot proceed due to a corrupted log, you may be prompted to use -L as a last resort. This clears the log and can result in loss of very recent metadata, so it should only be used if the filesystem will not mount otherwise.

---

If the disk is ReiserFS

Use reiserfsck:

reiserfsck --check /dev/mdX

In more severe cases, --rebuild-tree may be required. ReiserFS is deprecated and more fragile, so ensure backups of important data before rebuilding. Migration to XFS should be treated as a separate step after stability is restored.

---

If the disk or pool is BTRFS (common for cache pools)

Preferred first step:

btrfs scrub start -Bd /mnt/cache

Be cautious with btrfs check --repair, as it can be destructive if used improperly.

---

4) Verify and monitor

After repair:

• Start the array normally

• Re-run the operation that originally triggered the error

• Monitor System Log for new filesystem or disk errors

If the error returns after a successful repair, this often points to hardware instability (disk, cabling, power, or controller), not a software issue.