lima-vm/lima · error

failed to unregister %#q: %w

Error message

failed to unregister %#q: %w

What it means

During pkg/instance.Delete, the unregister step (which tears down driver resources and stops the hostagent socket server) failed. Lima wraps it with the instance directory path. Note unregister is only attempted when inst.Errors is empty; the delete of the instance directory is aborted so the instance remains registered.

Source

Thrown at pkg/instance/delete.go:29

	"github.com/lima-vm/lima/v2/pkg/driver/external/server"
	"github.com/lima-vm/lima/v2/pkg/driverutil"
	"github.com/lima-vm/lima/v2/pkg/limatype"
)

func Delete(ctx context.Context, inst *limatype.Instance, force bool) error {
	if inst.Protected {
		return errors.New("instance is protected to prohibit accidental removal (Hint: use `limactl unprotect`)")
	}
	if !force && inst.Status != limatype.StatusStopped {
		return fmt.Errorf("expected status %#q, got %#q", limatype.StatusStopped, inst.Status)
	}

	StopForcibly(inst)

	if len(inst.Errors) == 0 {
		if err := unregister(ctx, inst); err != nil {
			return fmt.Errorf("failed to unregister %#q: %w", inst.Dir, err)
		}
	}
	if err := os.RemoveAll(inst.Dir); err != nil {
		return fmt.Errorf("failed to remove %#q: %w", inst.Dir, err)
	}

	return nil
}

func unregister(ctx context.Context, inst *limatype.Instance) error {
	limaDriver, err := driverutil.CreateConfiguredDriver(ctx, inst, 0)
	if err != nil {
		return fmt.Errorf("failed to create driver instance: %w", err)
	}

	if err := limaDriver.Delete(ctx); err != nil {
		return fmt.Errorf("failed to delete driver instance: %w", err)
	}

View on GitHub (pinned to dd909d0973)

Solutions

1. Inspect the wrapped cause: 'failed to create driver instance' vs 'failed to delete driver instance'.
2. Retry after fixing the driver issue; if cleanup already partially ran, use --force or remove the instance dir manually.
3. As a last resort, manually `rm -rf ~/.lima/<instance>` after stopping the hostagent (`limactl stop -f`).
4. Keep lima.yaml in the instance dir intact so CreateConfiguredDriver can reconstruct the driver.

Example fix

// before
limactl delete myvm
// after
limactl stop -f myvm && limactl delete myvm

inst, _ := store.Inspect(ctx, instName)
if len(inst.Errors) > 0 {
    // unregister will be skipped; expect leftover driver resources
    _ = inst
}

if err := instance.Delete(ctx, inst, false); err != nil {
    if strings.Contains(err.Error(), "failed to unregister") {
        // inspect wrapped cause (create-driver vs delete-driver) and retry once
        return instance.Delete(ctx, inst, true)
    }
    return err
}

When it happens

Trigger: instance.Delete on a healthy instance (len(inst.Errors)==0) where unregister(ctx, inst) returns an error — e.g. CreateConfiguredDriver fails (see 648) or limaDriver.Delete fails (see 649).

Common situations: Driver resources (disk, ssh keys, network) cannot be cleaned because the driver config in the instance dir no longer matches the host, or the external driver process cannot be reached.

Related errors

• failed to create driver instance: %w
• failed to delete driver instance: %w
• failed to get boot scripts: %w
• invalid boot script filename %#q: must be in format 'boot.<O
• unimplemented by the krunkit driver

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