lima-vm/lima · error

read APFS superblock at offset

Error message

read APFS superblock at offset %d: %w

What it means

Thrown by openContainer after findAPFSPartitionGPT succeeds: the ReadAt of the NX superblock at the discovered APFS partition byte offset failed. The underlying error (short read near end of file, I/O error) is wrapped with the offset. This indicates the located APFS partition region is unreadable or the image is truncated partway into the partition.

Solutions

1. Verify the image file size covers the partition's first LBA (firstLBA*512 + 4096 bytes); re-copy the full image if truncated.
2. Regenerate or re-export the disk image from a healthy source.
3. Check the underlying storage/disk for I/O errors (smartctl, dmesg).
4. If the image was shrunk, restore its original size so partition offsets are in range.

Example fix

// before
truncate -s 1G macos.img   // smaller than APFS partition start -> read fails
// after
cp --sparse=always full-macos.img macos.img   # copy the complete image

fi, err := os.Stat(diskPath)
// ensure the file is large enough for a plausible partition start + superblock
if err == nil && fi.Size() < 1024*1024 {
    return fmt.Errorf("image %q suspiciously small; likely truncated", diskPath)
}

if err := apfs.Chown(diskPath, role, uid, gid, paths...); err != nil {
    if strings.Contains(err.Error(), "read APFS superblock at offset") {
        // partition region unreadable/truncated: restore full image
    }
    return err
}

When it happens

Trigger: apfs.Chown on a GPT image where the APFS partition entry's first LBA points beyond the end of the file (truncated image) or to an unreadable region of a device; storage I/O errors at that offset.

Common situations: A partially copied/cloned disk image where the partition table survived but the partition data did not; a sparse image with an unmaterialized region; resizing an image smaller than the partition layout expects; faulty disk or flaky USB-attached target.

Related errors

• finding APFS partition
• open disk
• read block 0
• chown inode (%#q)
• directory entry %#q not found

AI-assisted analysis of lima-vm/lima@dd909d0973 (2026-09-01). Data as JSON: /api/errors/f5506de34661deba. Report an issue: GitHub.

Appendix: source

Thrown at pkg/apfs/chown.go:91

	if _, err := f.ReadAt(hdr, 0); err != nil {
		f.Close()
		return nil, fmt.Errorf("read block 0: %w", err)
	}

	if le.Uint32(hdr[nxMagicOff:]) == nxMagic {
		// Raw APFS container (no partition table).
		c.blockSize = le.Uint32(hdr[nxBlockSizeOff:])
	} else {
		// Look for a GPT partition table and find the APFS partition.
		offset, err := findAPFSPartitionGPT(f)
		if err != nil {
			f.Close()
			return nil, fmt.Errorf("finding APFS partition: %w", err)
		}
		c.baseOffset = offset
		if _, err := f.ReadAt(hdr, offset); err != nil {
			f.Close()
			return nil, fmt.Errorf("read APFS superblock at offset %d: %w", offset, err)
		}
		if le.Uint32(hdr[nxMagicOff:]) != nxMagic {
			f.Close()
			return nil, fmt.Errorf("APFS partition at offset %d has bad magic", offset)
		}
		c.blockSize = le.Uint32(hdr[nxBlockSizeOff:])
	}

	if c.blockSize < 4096 {
		f.Close()
		return nil, fmt.Errorf("invalid block size %d", c.blockSize)
	}
	return c, nil
}

// GPT constants.
const (
	gptHeaderSignature = "EFI PART"

View on GitHub (pinned to dd909d0973)