2.2 Beta 3: raw disk resize silently fails with a 7-sector gap after Recovery

[AFutureD]

1. Context

This issue occurred while resizing an existing macOS VM after the disk-resize feature from PR #678 was released.

Component	Value
VirtualBuddy	2.2 Beta 3, build 402
Host	macOS 26.5.2, Apple Silicon
Guest	macOS 26.6
Image format	Raw
FileVault	Disabled
Original image size	64 GiB
Requested image size	117 GiB

The VM was originally installed from an Apple restore image.

2. Problem details and evidence

VirtualBuddy enlarged the raw image file, but did not update the GPT partition layout or APFS container.

Show read-only diagnostic commands

IMAGE="<Path Disk.img>"
VM_DIR="${IMAGE%/Disk.img}"

stat -f 'logical_bytes=%z' "$IMAGE"
du -h "$IMAGE"

plutil -p "$VM_DIR/.vbdata/Config.plist"
hdiutil imageinfo "$IMAGE"

I then attached the image read-only to inspect the partition map and APFS container:

ATTACH_OUTPUT="$(hdiutil attach -readonly -nomount "$IMAGE")"

PHYSICAL_DISK="$(
  printf '%s\n' "$ATTACH_OUTPUT" |
  awk '$2 == "GUID_partition_scheme" { print $1; exit }'
)"

diskutil list "$PHYSICAL_DISK"
diskutil info "${PHYSICAL_DISK}s2"

MAIN_CONTAINER="$(
  diskutil info -plist "${PHYSICAL_DISK}s2" |
  plutil -extract APFSContainerReference raw -o - -
)"

diskutil apfs list "$MAIN_CONTAINER"
diskutil apfs resizeContainer "${PHYSICAL_DISK}s2" limits

hdiutil detach "$PHYSICAL_DISK"

The result was:

Raw image:             64 GiB → 117 GiB
Main GPT partition:    remained 62.8 GB
APFS container:        remained 62.8 GB
resizePending:         false

The added space appeared after Recovery:

Main APFS (62.8 GB)
→ Recovery (5.4 GB)
→ newly added free space

Running the suggested command inside the guest, using the correct disk identifier, failed:

diskutil apfs resizeContainer disk0s2 0

Error:

-69519: A gap is required in the partition map,
but it is missing or too small

The primary GPT header and partition entries contained:

Image sector count:       245366784
Primary GPT backupLBA:    134217727
GPT lastUsableLBA:        134217694
Recovery last LBA:        134217687
Trailing gap:             7 sectors

GPTLayoutAdjuster currently requires:

recoveryLast == header.lastUsableLBA

In this Apple-created layout:

134217687 != 134217694

The geometry check therefore returns without moving Recovery or extending the main partition.

The backing file is still enlarged and resizePending is cleared, so the partial resize appears successful.

3. Approach taken

I stopped VirtualBuddy and worked on an APFS clone of the image.

I used a one-off Swift helper based on GPTLayoutAdjuster to validate the GPT, preserve the 7-sector trailing gap, move Recovery, extend the main APFS partition entry, and rebuild both GPT structures.

Show GPT repair commands

IMAGE="<Path Disk.img>"
WORK_DIR="$(mktemp -d "$(dirname "$IMAGE")/.resize-test.XXXXXX")"
WORK_IMAGE="$WORK_DIR/Disk.img"

/bin/cp -c -p "$IMAGE" "$WORK_IMAGE"

xcrun swiftc relocate_vb_recovery.swift \
  -o relocate_vb_recovery \
  -lz

./relocate_vb_recovery "$WORK_IMAGE"

After the GPT repair, the physical-store partition was 119,734,796,288 bytes while the APFS container ceiling was still 62,826,479,616 bytes.

A direct grow-to-fit still returned -69519. A 16 MiB shrink/grow nudge forced APFS to refresh its capacity.

Show APFS resize and verification commands

ATTACH_OUTPUT="$(hdiutil attach -nomount "$WORK_IMAGE")"

PHYSICAL_DISK="$(
  printf '%s\n' "$ATTACH_OUTPUT" |
  awk '$2 == "GUID_partition_scheme" { print $1; exit }'
)"

diskutil verifyDisk "$PHYSICAL_DISK"
diskutil list "$PHYSICAL_DISK"

# This direct grow-to-fit attempt reproduced error -69519.
diskutil apfs resizeContainer "${PHYSICAL_DISK}s2" 0

PARTITION_SIZE="$(
  diskutil info -plist "${PHYSICAL_DISK}s2" |
  plutil -extract TotalSize raw -o - -
)"

NUDGE_SIZE="$((PARTITION_SIZE - 16 * 1024 * 1024))"

diskutil apfs resizeContainer \
  "${PHYSICAL_DISK}s2" \
  "${NUDGE_SIZE}B"

diskutil apfs resizeContainer "${PHYSICAL_DISK}s2" 0

MAIN_CONTAINER="$(
  diskutil info -plist "${PHYSICAL_DISK}s2" |
  plutil -extract APFSContainerReference raw -o - -
)"

diskutil apfs list "$MAIN_CONTAINER"
diskutil verifyDisk "$PHYSICAL_DISK"
hdiutil detach "$PHYSICAL_DISK"

Final verified state:

APFS container:  119734796288 bytes
APFS free space: 65482518528 bytes
Recovery:        readable
GPT verification: passed
fsck_apfs:       passed twice

Only after these checks passed did I replace the affected image with the verified clone. The original VM had already been backed up.

4. Suggestions

1. Accept a small, bounded gap between recoveryLast and lastUsableLBA.
2. Add a regression test with the observed 7-sector Apple restore-image gap.
3. Report a GPT adjustment no-op as an error instead of completing silently.
4. Verify the GPT and Recovery postconditions before clearing resizePending.
5. Allow retrying when the image already has the requested size but its GPT remains at the old size.

[AFutureD]

I have almost no prior knowledge of raw disk images, GPT, or APFS internals.

After I encountered this issue, Codex helped me diagnose and repair the disk image.
Once the problem was resolved, I used Codex to organize the findings, commands, and suggested improvements into the report above.

I hope the technical details are useful to the developers.

[insidegui]

Paging @balcsida

[balcsida]

Checking