Interactive Troubleshooter

Published: Sep 20, 2026

Time Machine Backup Failed: Sparsebundle Repair

Time: 15 mins Level: Beginner

By StepDiag Engineering Team

Reviewed by Ibraheem Taofeeq Opeyemi

This diagnostic guide resolves corrupt macOS Time Machine sparsebundles and sparseimages, address verification failure alerts, and clears read-only lock attributes on NAS or local backup stores. It provides structured pathways to repair APFS and HFS+ file system structures, purge broken snapshot markers, and resume incremental backups.

Full Diagnostic Tree & Step-by-Step Overview

What error message or behavior occurs when Time Machine attempts to complete a backup?

Time Machine displays 'Time Machine completed a verification of your backups... must create a new backup' alert
Terminal/GUI error: 'The backup disk image ... is in use' or 'Resource temporarily unavailable'
Backup fails during file system check with 'fsck_apfs' or 'fsck_hfs' error code 8 or 255
Sparsebundle mounts as Read-Only or throws 'No mountable file systems' error

What type of storage destination holds the problematic Time Machine sparsebundle image?

Network Attached Storage (NAS, Synology, QNAP, or TrueNAS) via SMB/AFP
Network share hosted on another Mac via macOS File Sharing
Locally attached External Hard Drive or Direct Attached Storage (USB/Thunderbolt)
Legacy Apple Time Capsule or AirPort Extreme USB shared drive

Repair NAS-based Sparsebundle via Terminal, Reset Verification State, and Clear Lock Flags

Solution:

Root Cause: Network Drop during Catalog Mutation

A network disruption during an active SMB write operation causes the macOS sync daemon (backupd) to mark the sparsebundle state as corrupted inside the image's Info.plist file (VerificationState = 2). The system forces a read-only lock to prevent further data loss.

# Diagnostic Verification:

Inspect system logs for Time Machine verification failures:

bash
log show --predicate 'subsystem == "com.apple.TimeMachine"' --info --last 24h | grep -E "Verification|Failed|sparsebundle"

Verify image plist internal state tags:

bash
defaults read /Volumes/backup_share/YourBackup.sparsebundle/Info.plist VerificationState

If the output is 2, the image has been flagged as permanently damaged.

# Step-by-Step Fix:

1. Open Terminal and elevate to root execution privileges:

bash
sudo su -

2. Clear immutable flags on the bundle metadata structure:

bash
chflags -R nouchg /Volumes/backup_share/YourBackup.sparsebundle

3. Attach the sparse image to the dev tree without auto-mounting volumes:

bash
hdiutil attach -nomount -readwrite -noverify /Volumes/backup_share/YourBackup.sparsebundle

4. Identify the disk node assigned (e.g., /dev/disk3s2 or /dev/disk3s1) using diskutil list.
5. Run file system repair against the partition node (for APFS formatted sparsebundles):

bash
fsck_apfs -y -o /dev/disk3s2

*(If formatted as HFS+, use fsck_hfs -fy /dev/disk3s2 instead).*
6. Edit the Info.plist inside the .sparsebundle container to clear the damage flag:

Set VerificationState to 0 using defaults:

bash
defaults write /Volumes/backup_share/YourBackup.sparsebundle/Info.plist VerificationState -int 0

7. Eject the virtual disk node:

bash
hdiutil detach /dev/disk3

# Prevention & Long-Term Monitoring:

Disable Wi-Fi sleep states during SMB backup operations using pmset.

Refer to the Apple Official Time Machine Support Guide to verify SMB 3.0 protocol configurations on custom NAS deployments.

Clear Stale Server SMB Locks and Repair Host-Shared Sparsebundle

Solution:

Root Cause: Orphaned Open-File Handles on macOS Share Host

When backing up to a secondary Mac on the local network, an abrupt client disconnection leaves active file locks (smbd process open handles) on individual 8MB band files located inside the .sparsebundle/bands/ directory.

# Diagnostic Verification:

On the host Mac sharing the drive, check for active file locks using lsof:

bash
sudo lsof | grep -i "sparsebundle"

# Step-by-Step Fix:

1. On the host Mac, stop the sharing service or restart the SMB server daemon:

bash
sudo launchctl kickstart -k system/com.apple.smbd

2. Navigate to the shared storage drive on the host system.
3. Verify file permissions on the target sparsebundle:

bash
sudo chmod -R 777 /Volumes/Storage/Backups/YourBackup.sparsebundle
sudo chown -R root:wheel /Volumes/Storage/Backups/YourBackup.sparsebundle

4. On the client Mac, unmount the share, reconnect, and run a manual repair attach:

bash
hdiutil attach -nomount -readwrite -noverify -ignorebadchecksums /Volumes/SharedFolder/YourBackup.sparsebundle

5. Execute partition repair using diskutil:

bash
diskutil repairVolume /dev/diskXsY

*(Replace diskXsY with the actual assigned disk number).*
6. Eject the disk image node via hdiutil detach /dev/diskX and trigger a manual Time Machine backup.

# Prevention & Long-Term Monitoring:

Ensure both client and host Macs are updated to matching macOS point releases to prevent APFS volume structure mismatches.

Repair Direct Attached USB/Thunderbolt Sparsebundle and Fix Partition Map

Solution:

Root Cause: Physical Drive Disconnect during Core Storage / APFS Sync

Unplugging an external hard drive without unmounting triggers dirty bit flags on the APFS container superblock, causing subsequent backupd runs to fail or drop into recovery mode.

# Diagnostic Verification:

Check Disk Utility for grayed-out partitions or run diskutil via Terminal:

bash
diskutil verifyVolume /Volumes/BackupDriveName

# Step-by-Step Fix:

1. Connect the drive directly to the Mac (avoid unpowered USB hubs).
2. Prevent macOS from automatically mounting broken sub-volumes:

bash
sudo defaults write com.apple.frameworks.diskimages auto-mount -bool false

3. Attach the local bundle image manually:

bash
hdiutil attach -nomount -readwrite /Volumes/BackupDrive/YourBackup.sparsebundle

4. Run high-level repair on the underlying media layout:

bash
sudo fsck_apfs -q -y /dev/diskXs2

5. Re-enable automatic disk mounting:

bash
sudo defaults write com.apple.frameworks.diskimages auto-mount -bool true

6. Mount the repaired volume in Disk Utility by clicking Mount on the target container.

# Prevention & Long-Term Monitoring:

Always eject drives cleanly through Finder or diskutil unmountDisk before disconnecting hardware cables.

Fix Legacy AirPort Time Capsule Sparsebundle Corruptions

Solution:

Root Cause: HFS+ Journal Corruption on Aging Network Drives

Legacy AirPort Time Capsules utilize older Netatalk/AFP networking stacks and HFS+ file systems. Abrupt power outages lead to HFS+ journal corruption and corrupted B-Tree catalog nodes.

# Diagnostic Verification:

Mount the Time Capsule Data volume in Finder.

Run fsck_hfs verification in Terminal:

bash
fsck_hfs -v /Volumes/Data/YourBackup.sparsebundle

Look for errors stating Invalid B-tree node size or Keys out of order.

# Step-by-Step Fix:

1. Mount the internal Data share of the Time Capsule.
2. Force attach the sparsebundle while ignoring broken checksums:

bash
hdiutil attach -nomount -readwrite -noverify -ignorebadchecksums /Volumes/Data/YourBackup.sparsebundle

3. Note the /dev/diskX identifier for the Apple_HFS or APFS payload partition.
4. Rebuild the B-Tree structure using multi-pass force repair:

bash
fsck_hfs -rcfv /dev/diskXs2

*(Execute this step up to 3 times until the exit code returns 0).*
5. Detach the image:

bash
hdiutil detach /dev/diskX

# Prevention & Long-Term Monitoring:

Migrate legacy AirPort Time Capsule backups to modern SMB 3.0 NAS solutions or direct-attached APFS storage drives.

Which process or handle lock is preventing access to the sparsebundle image?

Orphaned `backupd` or `diskimagesiod` process locking the image file
Stale token lock file (`token` or `com.apple.TimeMachine.MachineID.plist`) inside bundle
Active Spotlight index (`mds` / `mds_stores`) locking sparseband files

Kill Orphaned Time Machine Daemon Processes and Release Locked Image Handles

Solution:

Root Cause: Hung `backupd` or `diskimagesiod` Background Process

When a Time Machine operation is forcibly canceled or interrupted by system sleep, background disk mounting daemons maintain active lock handles on the bundle, causing consecutive runs to fail with 'Resource temporarily unavailable'.

# Diagnostic Verification:

Query active processes touching the backup bundle:

bash
sudo ps aux | grep -E "backupd|diskimagesiod"

# Step-by-Step Fix:

1. Terminate running Time Machine daemons:

bash
sudo killall -9 backupd backupd-helper diskimagesiod

2. Verify no active processes hold open handles on the mount directory:

bash
sudo fuser -c /Volumes/YourBackupShare

3. Restart the Time Machine menu bar interface daemon:

bash
killall SystemUIServer

4. Trigger a clean backup sequence using tmutil:

bash
sudo tmutil startbackup --brief

# Prevention & Long-Term Monitoring:

Stop active backups cleanly using sudo tmutil stopbackup before initiating shutdown or sleep states.

Remove Internal Locks and Reset Machine ID Token Parameters

Solution:

Root Cause: Persistent Machine ID Lock Files

macOS writes lock files directly into the .sparsebundle container (com.apple.TimeMachine.MachineID.plist and token) to prevent multiple computers from writing to the same image simultaneously. Unexpected disconnections leave these lock files in an active state.

# Diagnostic Verification:

Inspect internal bundle directory contents for lock markers:

bash
ls -la /Volumes/BackupShare/YourBackup.sparsebundle/com.apple.TimeMachine.MachineID.*

# Step-by-Step Fix:

1. Navigate into the sparsebundle package directory:

bash
cd /Volumes/BackupShare/YourBackup.sparsebundle/

2. Remove the internal token lock file:

bash
sudo rm -f token lock

3. Edit com.apple.TimeMachine.MachineID.plist using plutil or text editor:

bash
sudo plutil -replace FixCompleted -int 1 com.apple.TimeMachine.MachineID.plist
sudo plutil -replace VerificationState -int 0 com.apple.TimeMachine.MachineID.plist

4. Remove extended lock attributes from the outer bundle directory:

bash
sudo xattr -d com.apple.FinderInfo /Volumes/BackupShare/YourBackup.sparsebundle

# Prevention & Long-Term Monitoring:

Ensure unique hostnames are assigned under System Settings > General > About for each Mac backing up to a shared network drive.

Exclude Sparsebundle Container from Spotlight Indexing and Purge mds Locks

Solution:

Root Cause: Spotlight Metadata Search Engine Lock

The macOS metadata indexing daemon (mds) attempts to scan newly modified 8MB band files inside the sparsebundle during active backups, resulting in lock contention against the backupd engine.

# Diagnostic Verification:

Track if mds is locking band files:

bash
sudo lsof | grep mds | grep sparsebundle

# Step-by-Step Fix:

1. Disable Spotlight indexing temporarily:

bash
sudo mdutil -i off /Volumes/BackupShare

2. Create a .metadata_never_index file inside the root of the backup drive and inside the sparsebundle container:

bash
touch /Volumes/BackupShare/.metadata_never_index
touch /Volumes/BackupShare/YourBackup.sparsebundle/.metadata_never_index

3. Prevent Spotlight from scanning the specific mount point via mdutil:

bash
sudo mdutil -d /Volumes/BackupShare

4. Unmount and remount the network volume, then restart the backup process.

# Prevention & Long-Term Monitoring:

Add external network backup destinations to the Spotlight Privacy Exclusion list inside macOS System Settings.

What underlying file system format is embedded inside your Time Machine sparse image?

APFS (Apple File System) formatted image (macOS 11 Big Sur and newer)
Mac OS Extended (Journaled / HFS+) formatted image (macOS 10.15 Catalina and older)
Hybrid / Converted container with broken APFS Superblock snapshots

Execute Low-Level Terminal APFS Container Repair via fsck_apfs

Solution:

Root Cause: Corrupted APFS Object Map or Volume Superblock

APFS stores backup snapshots in space-efficient tree structures. Corrupted object maps (omap) or unaligned checkpoint records cause fsck_apfs to return exit code 8 during pre-backup health verification checks.

# Diagnostic Verification:

Manually run APFS verification in Terminal to review exact failure codes:

bash
sudo fsck_apfs -v /dev/diskXs2

Look for errors like omap_val invalid or checkpoint transaction id invalid.

# Step-by-Step Fix:

1. Mount the raw sparse bundle image without mounting the APFS volume:

bash
hdiutil attach -nomount -readwrite -noverify /Volumes/Share/YourBackup.sparsebundle

2. Execute a full multi-pass repair using advanced flags:

bash
sudo fsck_apfs -y -o /dev/diskXs2

*(The -o flag forces repair of corrupted object maps).*
3. If fsck_apfs fails, attempt to repair using a shadow file to prevent destructive writes:

bash
sudo fsck_apfs -y -s /tmp/apfs_shadow /dev/diskXs2

4. Once repaired successfully, verify the volume status:

bash
diskutil verifyVolume /dev/diskXs2

5. Detach the disk node:

bash
hdiutil detach /dev/diskX

# Prevention & Long-Term Monitoring:

Avoid force-rebooting Macs while system logs report active APFS snapshot creation.

Execute HFS+ B-Tree Catalog Reconstruction using fsck_hfs

Solution:

Root Cause: Broken HFS+ Catalog File and Extents Overflow Tree

Legacy HFS+ sparsebundles use a single centralized catalog file to track file allocation. If the allocation bitmap mismatches the actual allocated blocks, fsck_hfs aborts with status code 8 or 255.

# Diagnostic Verification:

Attempt manual HFS+ verification:

bash
sudo fsck_hfs -l /dev/diskXs2

# Step-by-Step Fix:

1. Attach the bundle to obtain raw block access:

bash
hdiutil attach -nomount -readwrite -noverify -ignorebadchecksums /Volumes/Share/YourBackup.sparsebundle

2. Force repair and rebuild the extent overflow B-tree:

bash
sudo fsck_hfs -Re -df /dev/diskXs2

3. If structural errors persist, run a deep memory-allocation repair pass:

bash
sudo fsck_hfs -fy -m 512M /dev/diskXs2

4. Unmount the disk node:

bash
hdiutil detach /dev/diskX

# Prevention & Long-Term Monitoring:

Convert legacy HFS+ backup containers to modern APFS destinations for improved fault tolerance.

Revert Damaged APFS Superblock to Pre-Corrupted Checkpoint Snapshot

Solution:

Root Cause: Corrupted Active APFS Checkpoint

APFS stores historical checkpoints of its container superblock. If the current active checkpoint becomes unreadable, fsck_apfs fails to reconcile the volume geometry.

# Diagnostic Verification:

Check for older available APFS checkpoints using fsck_apfs:

bash
sudo fsck_apfs -m /dev/diskXs2

# Step-by-Step Fix:

1. Attach the bundle in read-write mode without mounting:

bash
hdiutil attach -nomount -readwrite /Volumes/Share/YourBackup.sparsebundle

2. Force fsck_apfs to revert the container to the last valid historical checkpoint:

bash
sudo fsck_apfs -y -c /dev/diskXs2

3. Verify that the volume mounts cleanly in read-only mode to confirm structural integrity:

bash
diskutil mount readOnly /dev/diskXs2

4. Unmount the volume and detach the device node:

bash
diskutil unmount /dev/diskXs2
hdiutil detach /dev/diskX

# Prevention & Long-Term Monitoring:

Maintain continuous uninterrupted power delivery (UPS) to network shares hosting Time Machine drives.

What specific file system mounting or permission error is being generated?

Image mounts as Read-Only despite disk permissions set to Read-Write
Terminal throws 'No mountable file systems' error during attach operation
Individual band files inside `.sparsebundle/bands` are missing or corrupted (0-byte size)

Clear Extended System File Attributes and Reset Bundle Mount Flags

Solution:

Root Cause: Immutable System Attribute Flags (`UC_IMMUTABLE` / `SF_IMMUTABLE`)

macOS sets system-level immutable flags on disk image directory containers when an unrecoverable verification failure occurs, restricting write operations at the kernel vnode level.

# Diagnostic Verification:

Check active file flags on the bundle container using ls -lo:

bash
ls -ldo /Volumes/BackupShare/YourBackup.sparsebundle

Look for the uchg or schg flags in the output list.

# Step-by-Step Fix:

1. Recursively strip user and system immutable flags:

bash
sudo chflags -R nouchg /Volumes/BackupShare/YourBackup.sparsebundle
sudo chflags -R noschg /Volumes/BackupShare/YourBackup.sparsebundle

2. Reset ownership attributes to the primary user account:

bash
sudo chown -R $(whoami):staff /Volumes/BackupShare/YourBackup.sparsebundle

3. Remove the Finder quarantine and lock extended attributes:

bash
sudo xattr -cr /Volumes/BackupShare/YourBackup.sparsebundle

4. Mount the image in read-write mode:

bash
hdiutil attach -readwrite /Volumes/BackupShare/YourBackup.sparsebundle

# Prevention & Long-Term Monitoring:

Avoid manually altering file permissions or executing chmod scripts on active backup folders.

Bypass Corrupted Partition Header and Mount Raw Disk Volume Node

Solution:

Root Cause: Invalid GUID Partition Table (GPT) or Primary Header Block

If the primary GPT partition header at block 0 of the sparsebundle becomes corrupted, hdiutil fails to parse the embedded volume structure and throws 'No mountable file systems'.

# Diagnostic Verification:

Query disk image headers using hdiutil imageinfo:

bash
hdiutil imageinfo /Volumes/BackupShare/YourBackup.sparsebundle

If partition scheme output returns unrecognized or corrupt, primary GPT headers are damaged.

# Step-by-Step Fix:

1. Attach the bundle ignoring partition table constraints:

bash
hdiutil attach -nomount -readwrite -kernel -ignorebadchecksums /Volumes/BackupShare/YourBackup.sparsebundle

2. Locate the raw disk node representing the whole disk (e.g., /dev/disk3).
3. Attempt to recover the secondary (backup) GPT header using gpt:

bash
sudo gpt recover /dev/diskX

4. If GPT recovery fails, mount the underlying file system partition directly using its sector offset:

bash
sudo diskutil mount readOnly /dev/diskXs2

5. Copy critical backup archives out of the mounted volume to a fresh storage destination.

# Prevention & Long-Term Monitoring:

Ensure network storage shares use battery-backed write caches to prevent raw header corruption during power outages.

Isolate Missing Band Files and Reconstruct Sparsebundle Token Registry

Solution:

Root Cause: Missing or Zero-Byte Band Slices in Bundle Container

Time Machine sparsebundles store raw disk data in numbered 8MB block files located inside the bands subdirectory. If a file transfer drops, zero-byte bands are left behind, breaking the sequential block sequence.

# Diagnostic Verification:

Scan for zero-byte band files inside the sparse bundle package:

bash
find /Volumes/BackupShare/YourBackup.sparsebundle/bands/ -type f -size 0

# Step-by-Step Fix:

1. Navigate to the bands directory:

bash
cd /Volumes/BackupShare/YourBackup.sparsebundle/bands/

2. Move all zero-byte band files to a temporary quarantine directory outside the bundle:

bash
mkdir /tmp/corrupt_bands
find . -type f -size 0 -exec mv {} /tmp/corrupt_bands/ \;

3. Attach the sparse bundle in read-write mode to allow fsck to heal missing storage blocks:

bash
hdiutil attach -nomount -readwrite -ignorebadchecksums /Volumes/BackupShare/YourBackup.sparsebundle

4. Execute file system repair to fill unallocated space and restore directory entries:

bash
sudo fsck_apfs -y /dev/diskXs2

5. Eject the image once repairs conclude successfully:

bash
hdiutil detach /dev/diskX

# Prevention & Long-Term Monitoring:

Perform scheduled health checks on network storage pools using ZFS/RAID scrub utilities to catch silent data rot.

Related Diagnostic Guides

OneDrive Recycle Bin Version Conflict: Restore Correct File

Google Photos Backup Duplicate Photos: Deduplication

NAS Drive Shows Degraded Pool With No Failed Disk

SSD Health 90% But Slow: DRAM Cache & Performance Diagnostic

Dual GPU Laptop Using Integrated Instead of Dedicated GPU

Subscribe to StepDiag

Embed Guide on Your Website