md-raid-deadlock-recovery

Diagnose Linux mdadm RAID5/6 stripe-cache deadlocks and execute a safe reboot workflow.

Updated Apr 4, 2026
One-click install
npx skills add https://github.com/saintgo7/claude-skills --skill md-raid-deadlock-recovery
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: md-raid-deadlock-recovery
Source: https://github.com/saintgo7/claude-skills/tree/main/md-raid-deadlock-recovery
Command: npx skills add https://github.com/saintgo7/claude-skills --skill md-raid-deadlock-recovery

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

This Skill prevents and resolves Linux mdadm RAID5/6 stripe-cache deadlocks that freeze mdcheck and system IO, where disks look healthy (SMART PASSED) but fsync/COMMIT and container writes hang until the system is rebooted.

Core Features & Use Cases

  • Diagnose the deadlock pattern: Detect high load with iowait, many blocked (D-state) processes, frozen sync_action, near-zero sync speed, and kernel stack evidence consistent with raid5_get_active_stripe lock contention.
  • Make reboot safe and repeatable: Disable RAID auto rechecks (mdcheck/mdadm autocheck), skip root fsck when appropriate, ensure SSH backup access via Cloudflare Tunnel, and verify container restart policies so services come back.
  • Verify recovery immediately after reboot: Re-check blocked process counts, confirm RAID sync_action returns to idle, validate /data writeability, and confirm critical service reachability.

Quick Start

Run the diagnose script with your md device name to confirm the deadlock pattern, then follow the pre-reboot hardening script before rebooting.

Frequently Asked Questions about md-raid-deadlock-recovery

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix an mdadm RAID5 deadlock when system IO hangs but disks are healthy?

To fix an mdadm RAID5 deadlock where system IO hangs despite healthy SMART statuses, diagnose the kernel lock pattern showing raid5_get_active_stripe contention and execute a safe reboot workflow with recovery hardening. This resolves frozen sync_action and stalled container writes.

Why does mdcheck freeze and block processes on my Linux RAID5 array?

mdcheck freezes and blocks processes due to raid5_get_active_stripe stripe-cache lock contention in the kernel. When sync_action is frozen and sync speed drops to near-zero, fsync operations and container writes stall indefinitely until a system reboot.

How do I safely reboot Linux during a production RAID deadlock without losing data?

To safely reboot during a production RAID deadlock, run pre-reboot hardening scripts to disable mdcheck timers and mdadm autocheck, tune root fsck mount-count when safe, validate Cloudflare Tunnel SSH access, and verify container restart policies before initiating the reboot.

What should I check after rebooting a server to recover from a RAID5 deadlock?

After rebooting to recover from a RAID5 deadlock, run a post-reboot verification pass to confirm RAID sync_action returns to idle, validate /data writeability, check container health, and perform optional HTTP health checks to ensure critical service reachability.

Can I recover from a RAID6 stripe-cache deadlock without disrupting container workloads?

Recovering from a RAID6 stripe-cache deadlock requires a system reboot, but you can minimize container workload disruption by assessing and verifying container restart policies beforehand. This ensures services come back automatically post-reboot.

Does mdadm autocheck need to be disabled before rebooting a frozen RAID array?

Yes, mdadm autocheck and mdcheck timers must be disabled before rebooting a frozen RAID array. This prevents the stripe-cache deadlock condition from immediately re-triggering upon boot, allowing the array to return to a clean idle state.