abiosoft/colima · error

error initiating container runtime: %w

Error message

error initiating container runtime: %w

What it means

Returned by colimaApp.containerEnvironment (app/app.go:574) when environment.NewContainer fails to construct a container runtime implementation for the given name. The %w wraps the underlying error, which typically names the unsupported/unknown runtime string. It means the runtime requested (from stored settings or 'kubernetes') cannot be mapped to a registered container implementation in this colima build.

Source

Thrown at app/app.go:574

		env, err := c.containerEnvironment(runtime)
		if err != nil {
			return nil, err
		}
		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())

View on GitHub (pinned to c3a5f9184d)

Solutions

1. Inspect the wrapped error (%w) — it identifies the offending runtime name
2. Check the profile settings (colima list -j, or ~/.colima/<profile>/colima.yaml) for an unexpected runtime value
3. Restart with an explicit supported runtime: `colima start -p <profile> --runtime docker`
4. If the profile predates the current colima version, `colima delete -p <profile>` and recreate it

Example fix

// before
env, err := c.containerEnvironment(runtime) // runtime from older settings
if err != nil { return err }

// after
// validate before constructing
switch runtime {
case docker.Name, containerd.Name:
    // known runtimes

default:
    return fmt.Errorf("unsupported runtime '%s', recreate the profile with `colima start --runtime docker`", runtime)
}
env, err := c.containerEnvironment(runtime)

// Validate the runtime string against supported values before constructing
var supported = map[string]bool{
    "docker": true, "containerd": true,
}
if !supported[runtime] {
    return fmt.Errorf("unsupported runtime '%s'; use docker or containerd", runtime)
}
env, err := c.containerEnvironment(runtime)

if _, err := c.containerEnvironment(runtime); err != nil {
    if strings.HasPrefix(err.Error(), "error initiating container runtime") {
        // runtime name unknown to this build: recreate profile with a supported runtime
    }
    return err
}

When it happens

Trigger: Calling containerEnvironment(runtime) with a runtime string that environment.NewContainer does not recognize: a corrupted settings value, a runtime renamed/removed across colima versions (e.g. containerd/incus availability differs per version), or Kubernetes() with the kubernetes environment unavailable in this build.

Common situations: Profile migrated between colima versions with different runtime registries; manually edited ~/.colima/<profile>/colima.yaml with a typo'd runtime; running a stripped-down fork where docker/containerd are not registered.

Related errors

• 'colima model' requires docker runtime, current runtime is %
• error starting %s: %w
• runtime disk provisioned for %s runtime. Delete container da
• 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/07e86ab1f91f5db2. Report an issue: GitHub.