{"record":{"id":"1c53211f416f6686","repo":"lima-vm/lima","slug":"reading-container-superblock-w","errorCode":null,"errorMessage":"reading container superblock: %w","messagePattern":"reading container superblock: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/apfs/chown.go","lineNumber":239,"sourceCode":"\t\t\tcontinue\n\t\t}\n\t\txid := le.Uint64(blk[objXIDOff:])\n\t\tif xid > bestXID {\n\t\t\tbestXID = xid\n\t\t\tbestBlock = blk\n\t\t}\n\t}\n\tif bestBlock == nil {\n\t\treturn nil, errors.New(\"no valid container superblock found in checkpoint area\")\n\t}\n\treturn bestBlock, nil\n}\n\n// findVolume locates the volume with the given role.\nfunc (c *container) findVolume(role uint16) (*volumeInfo, error) {\n\tsb, err := c.latestSuperblock()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"reading container superblock: %w\", err)\n\t}\n\n\t// Read the container omap to resolve volume virtual OIDs.\n\tcontainerOmapAddr := le.Uint64(sb[nxOmapOIDOff:])\n\tcontainerOmap, err := c.readBlock(containerOmapAddr)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"reading container omap at %d: %w\", containerOmapAddr, err)\n\t}\n\tcontainerOmapTreeAddr := le.Uint64(containerOmap[omapTreeOIDOff:])\n\n\tcontainerXID := le.Uint64(sb[objXIDOff:])\n\n\tfor i := range nxMaxFileSystems {\n\t\toff := nxFSOIDOff + i*8\n\t\tvolOID := le.Uint64(sb[off:])\n\t\tif volOID == 0 {\n\t\t\tcontinue\n\t\t}","sourceCodeStart":221,"sourceCodeEnd":257,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/apfs/chown.go#L221-L257","documentation":"This error is returned by findVolume when it cannot locate the newest valid APFS container superblock via latestSuperblock. The container superblock is required to find the container omap and enumerate volumes, so without it no operation can proceed. It is always a wrapper around a lower-level cause (checksum failure, unreadable block, or no valid superblock in the checkpoint descriptor area).","triggerScenarios":"Calling apfs.Chown (or anything invoking findVolume) on a disk image whose checkpoint descriptor area contains no block passing checksum, magic, and objectTypeNXSuperblock validation, or whose block 0 fails its fletcher checksum, or whose blocks cannot be read from the image file.","commonSituations":"Pointing Chown at a non-APFS image (ext4, qcow2 without raw layout), a truncated or corrupted disk image, an image written while the guest was still running, or an APFS container formatted by a newer macOS with structures this parser does not understand.","solutions":["Verify the diskPath points to a raw APFS image (or GPT disk containing an APFS container), not a VM disk format or a filesystem image of another type.","Check block 0 and the checkpoint descriptor area with a hex dump to confirm APFS magic 'NXSB' is present.","Re-copy or re-export the disk image; the source may be truncated or corrupted.","Shut down the VM/instance cleanly before taking the image so the checkpoint area is consistent.","Run fsck_apfs on the image from a macOS host to repair container metadata."],"exampleFix":"// before\nerr := apfs.Chown(\"/vms/mac/disk.qcow2\", apfs.VolRoleData, 501, 20, \"Library/LaunchDaemons/x.plist\")\n// after\n// convert to raw first: qemu-img convert -O raw disk.qcow2 disk.raw\nerr := apfs.Chown(\"/vms/mac/disk.raw\", apfs.VolRoleData, 501, 20, \"Library/LaunchDaemons/x.plist\")","handlingStrategy":"validation","validationCode":"func looksLikeRawAPFSImage(path string) error {\n\tf, err := os.Open(path)\n\tif err != nil { return err }\n\tdefer f.Close()\n\thdr := make([]byte, 4096)\n\tif _, err := f.ReadAt(hdr, 0); err != nil { return err }\n\tif string(hdr[32:36]) == \"NXSB\" { return nil } // magic at nxMagicOff\n\t// else require a GPT with an APFS partition\n\treturn errors.New(\"not a raw APFS container image\")\n}","typeGuard":null,"tryCatchPattern":"if err := apfs.Chown(diskPath, role, uid, gid, paths...); err != nil {\n\tif strings.Contains(err.Error(), \"reading container superblock\") {\n\t\treturn fmt.Errorf(\"%w: verify %s is a raw APFS image and not truncated\", err, diskPath)\n\t}\n\treturn err\n}","preventionTips":["Always take disk images from cleanly shut-down VMs.","Convert qcow2/vdi to raw before passing to this library.","Verify image checksums after transfer to catch truncation.","Keep macOS guest versions within the range the parser supports."],"tags":["apfs","disk-image","corruption"],"backgroundTag":"apfs-superblock-unreadable","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}