If you have ever run zpool status after a scrub and seen a non-zero number under the CKSUM column, you already know the mild panic it triggers. ZFS checksum errors after a scrub mean one thing for certain: data on disk and the checksum stored for that data no longer agree. Whether that one error is harmless or the leading edge of a hardware problem is the question this guide is built to answer.
I have been running ZFS pools in home labs and small production environments for years, and the same question comes up over and over: do I worry, do I clear the counter, do I replace a disk, or do I do nothing? In the next 3,500 words, I will walk you through exactly what ZFS checksum errors are, how scrubs detect and repair corruption, how to read the output, when to be concerned, and how to clear the errors safely without masking an underlying problem.
Table of Contents
What Are ZFS Checksum Errors and Why Do They Occur?
ZFS checksum errors occur when the checksum stored alongside a block does not match the checksum that ZFS recalculates when reading that block back from disk. This mismatch is the filesystem’s way of telling you that something on the storage medium has changed without the filesystem’s knowledge.
ZFS uses end-to-end checksums, which is a critical concept. The checksum is calculated when data is written, stored as part of the block pointer, and re-verified every time the block is read. Unlike traditional RAID controllers that verify data only between the controller and the disk, ZFS checksums travel with the data all the way up to the application layer. This is what gives ZFS its famous ability to detect silent data corruption, the kind that other filesystems miss entirely.
The most common causes of checksum errors include:
Bit rot: gradual magnetic degradation of stored data on spinning disks over months and years.
Media degradation on SSDs: NAND cells lose charge or wear out, causing bits to flip.
Hardware failures: failing disks, dying HBA cards, loose cables, or flaky backplanes.
Cosmic radiation and environmental factors: rare but real, especially in high-altitude data centers or systems without ECC memory.
PSU issues: unstable voltage can cause writes to land incorrectly on disk.
Non-ECC memory errors: if data is corrupted in RAM before being written, the corrupted data gets checksummed and stored, locking the corruption into the pool permanently.
The key insight is that checksum errors are not inherently bad news. What matters is the pattern, the count, the hardware involved, and whether the error is happening on one device or across an entire pool.
How ZFS Scrubs Detect and Repair Corruption
A ZFS scrub is a comprehensive integrity check that walks every allocated block in the pool, reads it back, and verifies its checksum. The scrub process follows a predictable sequence:
ZFS reads every block of data and metadata in the pool.
For each block, it recalculates the checksum using the configured algorithm (commonly fletcher4 or sha256).
It compares the calculated checksum against the stored checksum embedded in the parent block pointer.
If checksums match, the block is considered healthy.
If checksums differ, ZFS knows corruption has occurred and triggers the self-healing process.
Under the hood, ZFS organizes blocks in a Merkle tree structure. Each block contains a checksum of its child blocks. Validating the entire tree from the leaves up to the root lets ZFS verify the integrity of all data efficiently, without having to read every block sequentially.
Self-healing only works if your pool has redundancy. In a RAID-Z1 vdev (one disk of parity), RAID-Z2 (two disks of parity), RAID-Z3 (three disks of parity), or a mirror vdev, ZFS can reconstruct a corrupted block using the good copy or parity data from the other devices. The pool then writes the corrected block back to the damaged device, repairing it in place.
For self-healing to function, the scrub must compare at least two copies of a block. If you have a striped pool with no redundancy (essentially RAID-0), ZFS can detect corruption but cannot repair it. You will see the checksum error, but the pool will have no good copy to fall back on.
Interpreting zpool status Output
The zpool status command is your primary diagnostic tool. Here is an annotated example showing what each column means:
pool: tank
state: ONLINE
status: One or more devices has experienced an unrecoverable error. An
attempt was made to correct the error. Applications are unaffected.
action: Determine if the device needs to be replaced, then clear the errors
using 'zpool clear' or replace the device.
scan: scrub repaired 256K in 6h47m with 0 errors on Sun Aug 10 14:22:09 2026
config:
NAME STATE READ WRITE CKSUM
tank ONLINE 0 0 0
mirror-0 ONLINE 0 0 0
sda ONLINE 0 0 0
sdb ONLINE 0 0 12
sdc ONLINE 0 0 0
mirror-1 ONLINE 0 0 0
sdd ONLINE 0 0 0
sde ONLINE 0 0 0The three critical columns in the READ WRITE CKSUM section each tell you something different:
READ: count of blocks that could not be read from the device at all. A non-zero READ count typically indicates a hardware failure or a disk that has gone offline.
WRITE: count of blocks that could not be written to the device. Non-zero WRITE counts usually mean the disk is rejecting writes, often a sign of imminent failure.
CKSUM: count of blocks that were read successfully but failed checksum verification. Non-zero CKSUM values mean data corruption, often the earliest indicator of hardware degradation.
In the example above, sdb shows 12 CKSUM errors but zero READ errors. ZFS detected the corruption during the scrub, healed the affected blocks using the mirror, and the pool reports state: ONLINE. This is the ideal outcome: corruption was found and repaired without any data loss or downtime.
If you see unrecoverable error in the status output, it means ZFS found a block with no good copy. This usually indicates that the same logical block was corrupted on multiple devices in a redundancy group, which is rare but serious.
How to Clear and Resolve ZFS Checksum Errors After a Scrub?
Clearing ZFS checksum errors involves a few steps, but the right order matters. Here is the workflow I use and recommend.
Step 1: Let the Scrub Finish Its Repair Pass
If you ran a scrub and it reported errors, the first thing to check is whether the scrub itself repaired them. Look at the scan line:
scan: scrub repaired 256K in 6h47m with 0 errors on Sun Aug 10 14:22:09 2026The phrase “repaired 256K” tells you ZFS found 256 kilobytes of corrupted data and successfully rewrote it using the redundant copy. Once the scrub finishes and repairs everything it can, you often just need to clear the error counters with the zpool clear command.
Step 2: Use the zpool clear Command
The zpool clear command resets the error counters in the pool. It does not repair anything, repair happens during the scrub, but it clears the stale statistics so future runs start from a clean baseline:
zpool clear tank
zpool clear tank sdbYou can clear the entire pool or specify a single device. A common concern I have seen in forums is whether zpool clear prevents self-healing. It does not. The self-healing happens during the scrub when ZFS reads the block, finds a checksum mismatch, and rewrites the bad copy with the good one. The clear command only zeroes out the error count so you can see whether new errors appear after the next scrub.
Step 3: Identify Any Affected Files
Use the zpool events command to see a timeline of what happened during the scrub. To find specific files affected by corruption, run:
zpool events -v tank | grep -i checksumYou can also search the filesystem for damaged files using find combined with ZFS-specific checksums, though this is more advanced and rarely necessary if your pool has healthy redundancy.
Step 4: Address the Root Cause
This is the most important step and the one most guides skip. Clearing the counter does not fix the underlying cause. If your disk, cable, HBA, or PSU is failing, new errors will appear on the next scrub. Always investigate the hardware before assuming the issue is resolved.
Step 5: Schedule a Follow-Up Scrub
After clearing errors, schedule another scrub in a week or two. If the same errors reappear on the same device, you almost certainly have a hardware problem that needs replacement.
When to Worry vs. Ignore Minor ZFS Checksum Errors
Not all checksum errors warrant immediate action. The decision depends on count, pattern, and frequency.
The Decision Tree
Start by asking these questions in order:
Is the error count growing on each scrub? A handful of errors that stays constant over months is far less concerning than a count that doubles each month.
Are errors concentrated on one device? Errors on a single disk often point to that disk. Errors spread across multiple devices in the same pool often point to a shared component like a cable, HBA, or PSU.
Are READ or WRITE errors also present? If yes, the disk is having serious problems. If only CKSUM is non-zero, the disk is still functioning mechanically but has data integrity issues.
Is the count non-zero after the second scrub following a clear? One or two errors that do not repeat is usually transient. Persistent errors mean something is degrading.
What does SMART say? Run
smartctl -a /dev/sdXon the affected device. Reallocated sectors, pending sectors, or UDMA CRC errors are red flags.
General Thresholds
As a rough guide: a single checksum error on a 10 TB pool after the first scrub is often benign and may never repeat. Five to ten errors on a single disk, especially with growing numbers, warrants attention. Errors on multiple disks, or errors accompanied by SMART warnings, demands immediate investigation and likely hardware replacement.
The TrueNAS and r/zfs communities have a saying: a few checksum errors on every scrub on a single disk often means the disk is starting to fail. Errors on multiple disks at once almost always means the problem is shared hardware, the HBA, the cable, the backplane, or the PSU.
Common Hardware Causes of ZFS Checksum Errors
Understanding the hardware layer is what separates a casual ZFS user from one who can troubleshoot effectively. These are the components most likely to cause checksum errors, in roughly descending order of frequency.
Cables and Connections
A loose or damaged SATA or SAS cable is the single most common cause of intermittent checksum errors. SAS cables in particular can develop marginal connections that work fine for normal I/O but fail under the sustained read pressure of a scrub. Reseating both ends and replacing older cables with new, certified cables is the first troubleshooting step.
HBA and RAID Controllers
Host Bus Adapters, especially cheaper models, can develop thermal issues or firmware bugs that cause data corruption. A user on the TrueNAS forums famously resolved persistent checksum errors across six disks by re-pasting the heatsink on their HBA and adding a cooling fan. This is a real and surprisingly common issue in dense homelab builds.
Backplanes
Hot-swap backplanes, particularly in older server chassis, can develop poor contact on individual drive bays. If errors always appear on the same physical slot, swap the drive to a different bay and watch whether the errors follow the drive or stay with the slot.
Power Supply Units
An aging or overloaded PSU can deliver unstable voltage, particularly under load. A scrub is one of the most stressful workloads a pool will ever see, so a borderline PSU that works fine during normal operation can fail during a scrub. If you suspect this, try a known-good PSU or measure voltages with a multimeter.
Memory
Non-ECC memory is a particularly insidious cause. If RAM corrupts data before it is written to disk, the corrupted data is checksummed and stored, locking the corruption permanently into the pool. ECC memory catches these errors at the memory controller, which is why production ZFS deployments should always use ECC RAM when available.
Disk Itself
Finally, the disk itself can be failing. Run SMART long and short tests, check the reallocated and pending sector counts, and look for UDMA CRC errors. A disk that is developing bad sectors will throw CKSUM errors that grow over time.
ZFS Scrub vs Resilver: Key Differences
These two operations look similar but serve very different purposes.
| Aspect | Scrub | Resilver |
|---|---|---|
| Purpose | Verify integrity of all data | Rebuild redundancy after device replacement |
| Trigger | Scheduled or manual | Automatic after disk replacement |
| Scope | Every block in the pool | Only blocks stored on the replaced device |
| Repair action | Heals corrupted blocks using redundancy | Rebuilds entire device from parity or mirror |
| I/O priority | Lower priority, runs in background | Higher priority, completes faster |
| Detects new corruption? | Yes, primary purpose | Only incidentally |
A scrub is preventive maintenance. A resilver is recovery from a failure. Both can heal data, but only a scrub actively searches the entire pool for corruption. Running scrubs regularly is what makes resilvers possible without losing data, because the redundant copies or parity data stay healthy.
ZFS Pool Maintenance Best Practices
After working through thousands of scrub reports, the community consensus on best practices is clear and consistent.
Scrub Frequency
Run a scrub at least once per month on home and small business pools. Larger production pools often scrub weekly. The ZFS documentation suggests running scrubs frequently enough to catch errors before redundancy is exhausted, which depends on pool size and error rate.
Scrub Scheduling
Schedule scrubs during low-usage windows. A scrub on a large pool can take many hours and will impact performance. ZFS limits scrub I/O so it does not overwhelm the pool, but plan accordingly.
Monitor with ZED
The ZFS Event Daemon (ZED) sends notifications when checksum errors are detected, when a device fails, or when a scrub completes with errors. Configure ZED to email you on these events. On TrueNAS and FreeNAS systems, this is built into the web interface. On Linux, configure the zed.rc file with your SMTP details.
Combine with SMART Tests
Pair every scheduled scrub with a SMART short test on each disk. SMART tests catch physical disk problems that ZFS cannot see. The combination gives you a complete picture: ZFS handles logical corruption, SMART handles physical health.
Maintain Backups
Checksum errors and self-healing protect against silent corruption, but they do not protect against logical mistakes, accidental deletion, ransomware, or total pool loss. Maintain offsite backups regardless of how healthy your ZFS pool appears.
Document Baseline Error Counts
After each clean scrub, record the result. A growing baseline is a leading indicator of hardware degradation long before it becomes a failure. Many admins keep a spreadsheet or use monitoring tools like Grafana to track scrub history.
Use ECC Memory When Possible
For any ZFS deployment where data integrity matters, ECC memory is a worthwhile investment. It catches in-flight corruption that would otherwise be silently checksummed and stored.
Frequently Asked Questions
What causes checksum errors in ZFS?
ZFS checksum errors occur when data read from disk does not match its stored checksum. The most common causes are bit rot, hardware degradation in disks, loose or failing cables, HBA or controller issues, unstable PSU voltage, and on rare occasions cosmic radiation or non-ECC memory errors that corrupt data before it is written.
How do I clear ZFS checksum errors after a scrub?
Let the scrub complete so it can repair any corruption using redundant copies, then run zpool clear poolname to reset the error counters. This does not affect self-healing, which already happened during the scrub. Investigate hardware causes before assuming the issue is resolved, then schedule a follow-up scrub to verify no new errors appear.
Is it normal to have checksum errors on ZFS scrub?
A small number of checksum errors, especially after a first scrub on a new pool, is not uncommon and usually indicates early bit rot that ZFS heals automatically. Persistent errors, growing error counts, or errors across multiple disks indicate a real hardware problem that needs investigation.
What is the difference between READ errors and CKSUM errors in ZFS?
READ errors mean the disk could not return the requested block at all, usually a hardware or connectivity failure. CKSUM errors mean the block was read successfully but failed checksum verification, indicating the stored data has been altered. WRITE errors mean the disk rejected a write operation. CKSUM errors alone are usually the earliest warning sign of a degrading disk.
How often should I run ZFS scrubs?
Run a ZFS scrub at least once per month for home and small business pools, and weekly for larger production pools. The goal is to detect and repair corruption before it accumulates beyond your redundancy capacity. Combine scrubs with scheduled SMART tests for complete hardware health monitoring.
Conclusion
Understanding and clearing ZFS checksum errors after a scrub is one of those skills that pays back every time you run it. ZFS gives you an unusually honest view of your storage health, and learning to read that view turns silent corruption into a manageable maintenance task instead of a catastrophic surprise.
Start by running zpool status after every scrub, watch the CKSUM column for changes, clear the counters after repairs, and investigate any persistent or growing counts on the same hardware. Cables, HBAs, PSUs, and disks are the usual suspects in that order. Pair your scrubs with SMART tests and ZED notifications for a complete picture. Your data is worth the few minutes per week this takes.