lima-vm/lima · error

failed to create hard link from %#q to %#q: %w

Error message

failed to create hard link from %#q to %#q: %w

What it means

ensureIPSW creates a hard link from the cached .ipsw base file to the expected .ipsw path (the installer requires the .ipsw suffix and rejects symlinks). This error wraps os.Link failure — typically the destination already exists or the source/destination is unusable.

Source

Thrown at pkg/driver/vz/vm_darwin.go:979

		logrus.Debugf("Client network file GC'ed")
	})
	vmNetworkFiles = append(vmNetworkFiles, server, client)
	return server, client, nil
}

func ensureIPSW(instDir string) error {
	ipsw := filepath.Join(instDir, filenames.ImageIPSW)
	if osutil.FileExists(ipsw) {
		return nil
	}
	ipswBase := filepath.Join(instDir, filenames.Image)
	if _, err := os.Stat(ipswBase); err != nil {
		return err
	}
	// The installer wants the file to have ".ipsw" suffix.
	// The link is created as a hard link, as the installer does not accept symlinks.
	if err := os.Link(ipswBase, ipsw); err != nil {
		return fmt.Errorf("failed to create hard link from %#q to %#q: %w", ipswBase, ipsw, err)
	}
	return nil
}

View on GitHub (pinned to dd909d0973)

Solutions

1. Delete the stale destination file/link at the reported ipsw path and retry the operation
2. Remove the partially-created instance (`limactl delete <instance> --force`) and recreate it
3. Check disk space and permissions on the LIMA_HOME directory
4. Verify the cached .ipsw base file still exists and is on a filesystem supporting hard links

Example fix

// before
$ limactl start macos-test
// failed: failed to create hard link from ... to ...
// after
$ limactl delete macos-test --force
$ limactl start macos-test

if _, err := os.Stat(ipsw); err == nil {
    os.Remove(ipsw) // clear stale hard link before starting
}
if _, err := os.Stat(ipswBase); err != nil {
    return fmt.Errorf("cached ipsw missing: %w", err)
}

if err := start(); err != nil && strings.Contains(err.Error(), "failed to create hard link") {
    os.Remove(ipswPath) // then retry start
}

When it happens

Trigger: os.Link(ipswBase, ipsw) fails during macOS guest setup, e.g. because the destination hard link already exists (EEXIST from a previous partial run), or the source file vanished between the preceding os.Stat and the Link call.

Common situations: Interrupted previous installation leaving a stale link at the destination; read-only or full filesystem; the IPSW cache file in LIMA_HOME deleted between stat and link; permission problems in ~/.lima.

Related errors

• failed to stop VM after installation: %w
• failed to force stop VM after installation: %w
• failed to create temp file: %w
• failed to write temp plist: %w
• failed to register instance %#q to start at login: %w

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