abiosoft/colima · critical

dependency check failed for VM: %w

Error message

dependency check failed for VM: %w

What it means

Thrown by app.New() when the pre-flight dependency check on the Lima guest tooling fails. Before constructing the application, colima calls host.IsInstalled(guest) to verify the Lima/QEMU components the VM driver depends on. The wrapped error identifies exactly which dependency is missing or below the required version.

Source

Thrown at app/app.go:50

	Active() bool
	Start(config.Config) error
	Stop(force bool) error
	Delete(data, force bool) error
	SSH(args ...string) error
	Status(extended bool, json bool) error
	Version() error
	Runtime() (string, error)
	Update() error
	Kubernetes() (environment.Container, error)
}

var _ App = (*colimaApp)(nil)

// New creates a new app.
func New() (App, error) {
	guest := lima.New(host.New())
	if err := host.IsInstalled(guest); err != nil {
		return nil, fmt.Errorf("dependency check failed for VM: %w", err)
	}

	return &colimaApp{
		guest: guest,
	}, nil
}

type colimaApp struct {
	guest environment.VM
}

func (c colimaApp) startWithRuntime(conf config.Config) ([]environment.Container, error) {
	kubernetesEnabled := conf.Kubernetes.Enabled

	// Kubernetes can only be enabled for docker and containerd
	switch conf.Runtime {
	case docker.Name, containerd.Name:
	default:

View on GitHub (pinned to c3a5f9184d)

Solutions

1. Run `brew update && brew upgrade colima lima` so colima and its bundled lima stay version-matched
2. Verify the toolchain: `limactl --version` and check that `$(brew --prefix)/bin/limactl` resolves to the brew-installed copy
3. If installed from a GitHub release, re-download the matching release so the lima directory sits next to the colima binary
4. Remove any stale/older limactl installations that shadow the bundled toolchain on PATH

Example fix

# before
colima start
# error: dependency check failed for VM: ...

# after
brew update && brew upgrade colima lima
colima start

// verify the lima toolchain colima depends on before constructing the app
if _, err := exec.Command("limactl", "--version").CombinedOutput(); err != nil {
    return fmt.Errorf("lima toolchain missing; run `brew install lima` first: %w", err)
}
// safe to call app.New() now

if _, err := app.New(); err != nil {
    if strings.Contains(err.Error(), "dependency check failed") {
        // reinstall/upgrade colima+lima as a pair before any other action
    }
    return err
}

When it happens

Trigger: Any CLI invocation that constructs the app via app.New() (practically every colima command) when the Lima assets are absent, incomplete, or outdated: colima upgraded while lima stayed pinned, an interrupted brew upgrade, or a standalone colima binary running without its bundled lima directory.

Common situations: Fresh machine without `brew install lima`; version skew between colima and lima after upgrading only one of them; colima binary extracted from a GitHub release without the lima/ assets; a stale limactl earlier on PATH shadowing the bundled toolchain.

Related errors

• error starting vm: %w
• error stopping vm: %w
• error during teardown of vm: %w
• error retrieving current runtime: empty value
• dependency check failed for %s: %w

AI-assisted analysis of abiosoft/colima@c3a5f9184d (2026-08-15). Data as JSON: /api/errors/73a032104bd0eddf. Report an issue: GitHub.