lima-vm/lima · error

failed to attach disk: %w

Error message

failed to attach disk: %w

What it means

patchWriteGuestFiles attaches the instance disk image (ASIF) using attachImageWithRetry before mounting its Data volume to write guest files. If attaching fails after the retries (3 attempts), the underlying error is wrapped with this message.

Source

Thrown at pkg/guestpatch/macos/macos_darwin.go:55

}

// Patch prepares a macOS guest disk for first boot. It writes the
// LaunchDaemon plist, init script, and setup markers via a noowners
// mount, then fixes file ownership by patching APFS inode records
// directly on the raw disk image. No sudo required.
func Patch(ctx context.Context, disk string) error {
	if err := patchWriteGuestFiles(ctx, disk); err != nil {
		return err
	}
	return patchFixOwnership(ctx, disk)
}

// patchWriteGuestFiles attaches the disk image, mounts the Data
// volume with noowners, writes guest files, then detaches.
func patchWriteGuestFiles(ctx context.Context, disk string) error {
	attached, err := attachImageWithRetry(ctx, disk, 3)
	if err != nil {
		return fmt.Errorf("failed to attach disk: %w", err)
	}
	if attached == nil || attached.Data == "" {
		return errors.New("failed to find data slice in attached disk")
	}
	dataDevPath := "/dev/" + attached.Data
	defer func() {
		// Detaching the data slice is enough to detach the whole ASIF.
		if err := asifutil.DetachASIF(dataDevPath); err != nil {
			logrus.WithError(err).Warnf("failed to detach %#q (%#q)", dataDevPath, disk)
		}
	}()

	instDir := filepath.Dir(disk)
	mnt := filepath.Join(instDir, filenames.MntDir)
	if err := os.MkdirAll(mnt, 0o755); err != nil {
		return fmt.Errorf("failed to create mount point %#q: %w", mnt, err)
	}
	defer func() {

View on GitHub (pinned to dd909d0973)

Solutions

1. Check the wrapped cause for the specific attach failure from attachImageWithRetry.
2. Ensure the instance is stopped so the disk is not exclusively attached.
3. Verify the disk path exists and is a valid ASIF/image file (`ls -l`, file integrity).
4. Avoid concurrent Patch invocations on the same instance; retry after clearing stale attach state.

Example fix

// before: patching a running instance's disk
limactl patch inst (while inst is running) -> EBUSY on attach
// after
limactl stop inst && limactl patch inst

// before patching, ensure instance is stopped and disk exists
if inst.Status != "Stopped" {
	return fmt.Errorf("instance must be stopped before patching (status=%s)", inst.Status)
}
if _, err := os.Stat(disk); err != nil {
	return fmt.Errorf("disk image missing: %w", err)
}

if err := patchWriteGuestFiles(ctx, disk); err != nil {
	if strings.Contains(err.Error(), "failed to attach disk") {
		// wait for any stale attach to clear, then retry once
		time.Sleep(2 * time.Second)
		return patchWriteGuestFiles(ctx, disk)
	}
	return err
}

When it happens

Trigger: Patch -> patchWriteGuestFiles when attachImageWithRetry exhausts 3 attempts because the disk image is missing/corrupt, already exclusively attached, or the attach framework (ASIF) returns an error.

Common situations: Instance disk already attached to a running VM; disk path wrong or instance deleted; macOS DiskImages framework failing on a corrupt/incomplete image; concurrent patch attempts.

Related errors

• failed to find data slice in attached disk
• failed to create mount point %#q: %w
• failed to create temp file: %w
• failed to write temp plist: %w
• failed to install plist to %s: %w

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