lima-vm/lima · error

%s: %w

Error message

%s: %w

What it means

hcsWait drives an async HCS operation to completion via HcsWaitForOperationResult. If the initiating call already returned an error (callErr), it is re-wrapped as '<what>: <callErr>'. Otherwise the wrapped error comes from the HRESULT of WaitForOperationResult. The 'what' prefix names the failing phase (e.g. 'HcsCreateComputeSystem').

Source

Thrown at pkg/driver/hcs/hcs_api_windows.go:88

}

func hcsCreateOperation() (hcsOperation, error) {
	r0, _, e1 := syscall.SyscallN(procHcsCreateOperation.Addr(), 0, 0)
	if r0 == 0 {
		return 0, fmt.Errorf("HcsCreateOperation: %w", e1)
	}
	return hcsOperation(r0), nil
}

func hcsCloseOperation(op hcsOperation) {
	_, _, _ = syscall.SyscallN(procHcsCloseOperation.Addr(), uintptr(op))
}

// hcsWait drives one async HCS call to completion and returns the result
// document (which carries structured error info on failure).
func hcsWait(op hcsOperation, what string, callErr error) (string, error) {
	if callErr != nil {
		return "", fmt.Errorf("%s: %w", what, callErr)
	}
	var result *uint16
	r0, _, _ := syscall.SyscallN(procHcsWaitForOperationResult.Addr(),
		uintptr(op), uintptr(infiniteTimeout), uintptr(unsafe.Pointer(&result)))
	doc := coString(result)
	if err := hresultErr(r0); err != nil {
		return doc, fmt.Errorf("%s: %w (result: %s)", what, err, doc)
	}
	return doc, nil
}

func hcsCreateComputeSystem(id, configuration string) (hcsSystem, error) {
	op, err := hcsCreateOperation()
	if err != nil {
		return 0, err
	}
	defer hcsCloseOperation(op)

View on GitHub (pinned to dd909d0973)

Solutions

1. Read the '<what>:' prefix to identify which HCS phase failed and the inner callErr
2. Re-run limactl from an elevated shell if the inner error is access denied
3. Delete stale VM state for the instance and recreate it
4. Run 'limactl delete -f' on the broken instance, then start fresh

// require elevation: most callErr cases here are access denied
if !isAdmin() {
	return errors.New("re-run elevated: HCS calls commonly fail with access denied otherwise")
}

if err := limactl.Start(inst); err != nil {
	if strings.Contains(err.Error(), ": access is denied") {
		return fmt.Errorf("elevate permissions or fix WHP ACLs, then retry: %w", err)
	}
	return err
}

When it happens

Trigger: The initial HCS call (create/start/terminate/getState) returns non-nil callErr — invalid handle, access denied, or an invalid parameter passed to the API — so hcsWait bails before waiting on the result.

Common situations: Access denied from running without required privileges; corrupted VM state file making the create call reject parameters; HCS API rejecting a malformed configuration document; another process holds the compute system lock.

Related errors

• HcsCreateOperation: %w
• unimplemented
• %s: %w (result: %s)
• configuration is nil
• --condition=boot is only supported on macOS

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