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.