FreeBSD 14 – ZFS scrub runs extremely slowly – Fix & Prevention

📖 ~1 min read

Table of contents

1. Symptom & Impact
2. Environment & Reproduction
3. Root Cause Analysis
4. Quick Triage
5. Step-by-Step Diagnosis
6. Solution – Primary Fix
7. Solution – Alternative Approaches
8. Verification & Acceptance Criteria
9. Rollback Plan
10. Prevention & Hardening
11. Related Errors & Cross-Refs
12. References & Further Reading

Symptom & Impact

Scrub tasks take far longer than expected, extending maintenance windows and delaying data integrity checks.

Environment & Reproduction

Typical on fragmented pools or systems under sustained random I/O load.

zpool scrub tank
zpool status
zpool iostat -v 5

Root Cause Analysis

Concurrent workload contention, device queue saturation, or slow vdev members reduce scrub throughput.

Quick Triage

Check whether production load is starving scrub tasks.

gstat -dp
iostat -x 1
vmstat -i

Step-by-Step Diagnosis

Identify bottleneck devices and queue depth behavior.

zpool iostat -v 10
sysctl kstat.zfs.misc.scrub
smartctl -x /dev/ada0

Solution – Primary Fix

Run scrub during low-load windows and tune relevant ZFS limits conservatively.

sysctl vfs.zfs.scrub_delay=0
sysctl vfs.zfs.top_maxinflight=64
zpool scrub tank

Solution – Alternative Approaches

Stagger scrubs by pool, migrate heavy workloads, or replace weak devices to balance vdev performance.

Verification & Acceptance Criteria

Scrub progress rate improves and completion aligns with maintenance SLOs.

zpool status
zpool iostat -v 5

Rollback Plan

Revert temporary tuning values if interactive workload latency increases.

sysctl vfs.zfs.scrub_delay=4
sysctl vfs.zfs.top_maxinflight=32

Prevention & Hardening

Use periodic performance baselines and replace outlier disks before they impact scrub operations.

Related Errors & Cross-Refs

Can co-occur with checksum spikes, controller queue bottlenecks, and pool fragmentation pressure.

Related tutorial: View the step-by-step tutorial for freebsd-14.

View all freebsd-14 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

OpenZFS performance tuning notes and FreeBSD storage optimization resources.