abiosoft/colima · error

nerdctl only supports %s runtime

Error message

nerdctl only supports %s runtime

What it means

`colima nerdctl` is a thin wrapper that execs nerdctl against containerd inside the guest; it first resolves app.Runtime() and hard-fails unless it equals containerd.Name ('containerd'). With the default docker runtime the guest runs the docker engine, not raw containerd, so nerdctl has nothing to talk to. There is no conversion layer — the runtime must have been chosen at `colima start` time.

Source

Thrown at cmd/nerdctl.go:45

// nerdctlCmd represents the nerdctl command
var nerdctlCmd = &cobra.Command{
	Use:     "nerdctl",
	Aliases: []string{"nerd", "n"},
	Short:   "run nerdctl (requires containerd runtime)",
	Long: `Run nerdctl to interact with containerd.
This requires containerd runtime.

It is recommended to specify '--' to differentiate from Colima flags.
`,
	RunE: func(cmd *cobra.Command, args []string) error {
		app := newApp()
		r, err := app.Runtime()
		if err != nil {
			return err
		}
		if r != containerd.Name {
			return fmt.Errorf("nerdctl only supports %s runtime", containerd.Name)
		}

		// collect CONTAINERD_* and NERDCTL_* environment variables from the host
		var envVars []string
		for _, env := range os.Environ() {
			if strings.HasPrefix(env, "CONTAINERD_") || strings.HasPrefix(env, "NERDCTL_") {
				envVars = append(envVars, env)
			}
		}

		var nerdctlArgs []string
		if len(envVars) > 0 {
			// use 'sudo env VAR=value ... nerdctl' to pass environment variables
			nerdctlArgs = append([]string{"sudo", "env"}, envVars...)
			nerdctlArgs = append(nerdctlArgs, "nerdctl")
		} else {
			nerdctlArgs = []string{"sudo", "nerdctl"}
		}

View on GitHub (pinned to c3a5f9184d)

Solutions

1. Recreate the VM with containerd: `colima stop && colima delete && colima start --runtime containerd`, then `colima nerdctl -- version`
2. If you also need docker on that machine, use a separate profile: `colima start --profile nerd --runtime containerd`
3. Alternatively use the docker runtime's own CLI (`docker ...` via colima's socket) instead of nerdctl

Example fix

# before
$ colima nerdctl -- version
error: nerdctl only supports containerd runtime

# after
$ colima stop && colima delete
$ colima start --runtime containerd
$ colima nerdctl -- version

// gate nerdctl usage on the VM's runtime
status, _ := exec.Command("colima", "status").CombinedOutput() // reports runtime
if !strings.Contains(string(status), "containerd") {
    // recreate: colima delete && colima start --runtime containerd
}

When it happens

Trigger: `colima nerdctl ...` on a VM started with the default `--runtime docker`; a config/profile whose runtime is docker; scripts assuming nerdctl works on any colima install.

Common situations: Following nerdctl tutorials against a stock colima install; mixing docker CLI workflows with nerdctl workflows on the same profile; forgetting that runtime is a start-time decision, not a per-command flag.

Related errors

• %s exists, use --force to replace
• runtime disk provisioned for %s runtime. Delete container da
• error starting %s: %w
• error retrieving current runtime: empty value
• error initiating container runtime: %w

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