abiosoft/colima · error

dependency check failed for %s: %w

Error message

dependency check failed for %s: %w

What it means

Returned by colimaApp.containerEnvironment (app/app.go:577) when host.IsInstalled(env) fails: the host-side client CLI for the selected container runtime (docker, containerd/ctr, incus, or kubectl for the kubernetes environment) is missing or not functional on the macOS host. The %s is the runtime name, the %w carries the dependency-check detail.

Source

Thrown at app/app.go:577

		}
		containers = append(containers, env)
	}

	// detect and add kubernetes
	if k, err := c.containerEnvironment(kubernetes.Name); err == nil && k.Running(ctx) {
		containers = append(containers, k)
	}

	return containers, nil
}

func (c colimaApp) containerEnvironment(runtime string) (environment.Container, error) {
	env, err := environment.NewContainer(runtime, c.guest.Host(), c.guest)
	if err != nil {
		return nil, fmt.Errorf("error initiating container runtime: %w", err)
	}
	if err := host.IsInstalled(env); err != nil {
		return nil, fmt.Errorf("dependency check failed for %s: %w", runtime, err)
	}

	return env, nil
}

func (c colimaApp) Runtime() (string, error) {
	return c.currentRuntime(context.Background())
}

func (c colimaApp) Kubernetes() (environment.Container, error) {
	return c.containerEnvironment(kubernetes.Name)
}

func (c colimaApp) Active() bool {
	return c.guest.Running(context.Background())
}

func (c *colimaApp) Update() error {

View on GitHub (pinned to c3a5f9184d)

Solutions

1. Install the matching client for the runtime named in the error, e.g. `brew install docker` (docker CLI), or the containerd/incus/kubectl client
2. Verify from the same shell/environment colima uses: `docker version` (or `ctr version`, `kubectl version --client`) succeeds
3. Fix PATH so the binary resolves (check /opt/homebrew/bin and /usr/local/bin)
4. Alternatively switch to a runtime whose client is installed: `colima start --runtime <installed-runtime>`

Example fix

// before
env, err := c.containerEnvironment(runtime)
if err != nil { return err } // 'dependency check failed for docker: ...'

// after
import "os/exec"
if _, err := exec.LookPath("docker"); err != nil {
    return fmt.Errorf("docker CLI missing: install with `brew install docker` before continuing")
}
env, err := c.containerEnvironment(runtime)

import "os/exec"

clientForRuntime := map[string]string{
    "docker": "docker", "containerd": "ctr", "kubernetes": "kubectl",
}
if bin, ok := clientForRuntime[runtime]; ok {
    if _, err := exec.LookPath(bin); err != nil {
        return fmt.Errorf("%s CLI not installed; install it first (e.g. brew install %s)", runtime, bin)
    }
}

if _, err := c.containerEnvironment(runtime); err != nil {
    if strings.HasPrefix(err.Error(), "dependency check failed") {
        // host client missing: point user to install the CLI named in the error
    }
    return err
}

When it happens

Trigger: `colima start --runtime docker` (or colima update/kubernetes flows) when the matching client binary is not installed, not on PATH, or not executable in the shell/environment colima runs from. Also triggered via app.Kubernetes() when kubectl is absent.

Common situations: Fresh machine where the docker CLI was never installed (only Docker Desktop was assumed); brew formula unlinked or /opt/homebrew/bin missing from PATH in launchd/CI contexts; choosing containerd or incus runtime without the corresponding client installed.

Related errors

• dependency check failed for VM: %w
• error initiating container runtime: %w
• error setting up AI model runner: %w
• 'colima model' requires docker runtime, current runtime is %
• error listing models: %w

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