`limactl start --foreground` is not supported on Windows

Error message

`limactl start --foreground` is not supported on Windows

What it means

On Windows, the foreground hostagent mode (`limactl start --foreground`) is unimplemented: the unix implementation relies on exec/fork semantics unavailable on Windows, so the Windows stub returns this error unconditionally.

Source

Thrown at pkg/instance/start_windows.go:12

// SPDX-FileCopyrightText: Copyright The Lima Authors
// SPDX-License-Identifier: Apache-2.0

package instance

import (
	"errors"
	"os/exec"
)

func execHostAgentForeground(_ string, _ *exec.Cmd) error {
	return errors.New("`limactl start --foreground` is not supported on Windows")
}

View on GitHub (pinned to dd909d0973)

Solutions

Drop the --foreground flag; run `limactl start` normally and read ~/.lima/<instance>/ha.stderr.log for logs
Use WSL2 and run lima inside Linux where --foreground works
If you need foreground behavior on Windows, contribute a windows implementation of execHostAgentForeground

Example fix

:: before
limactl start --foreground my-instance
:: after
limactl start my-instance
:: logs: %USERPROFILE%\.lima\my-instance\ha.stderr.log

Defensive patterns

Strategy: fallback

Validate before calling

if runtime.GOOS == "windows" && foreground {
    return errors.New("--foreground is not supported on Windows; run without the flag")
}

Try / catch

if err != nil && strings.Contains(err.Error(), "not supported on Windows") {
    logrus.Warn("falling back to background hostagent")
    return startBackground()
}

Prevention

Don't pass --foreground on Windows hosts
Read hostagent logs from the instance dir instead
Run Linux VMs under WSL2 if foreground mode is required

When it happens

Trigger: Running `limactl start --foreground` (or Restart with foreground hostagent) on a Windows host.

Common situations: Windows users trying to see hostagent logs interactively, or following unix-oriented documentation/tutorials that use --foreground.

Related errors

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