abiosoft/colima · error

unknown runner type: %s (valid options: docker, ramalama)

Error message

unknown runner type: %s (valid options: docker, ramalama)

What it means

GetRunner is the factory mapping a RunnerType to its Runner implementation; only RunnerDocker and RunnerRamalama are handled, and everything else — including the empty string — falls to the default branch. RunnerType values originate from CLI flags or environment input, so this error indicates unvalidated external input reaching the factory.

Source

Thrown at model/runner.go:79

	// CheckSetup checks if setup/update is needed and returns version info.
	// This should be called before Setup() to display version info on primary screen.
	CheckSetup() (SetupStatus, error)
	// Setup installs or updates the runner.
	// Call CheckSetup() first to determine if setup is needed.
	Setup() error
	// GetCurrentVersion returns the currently installed version.
	GetCurrentVersion() string
}

// GetRunner returns the appropriate Runner based on type.
func GetRunner(runnerType RunnerType) (Runner, error) {
	switch runnerType {
	case RunnerDocker:
		return &dockerRunner{}, nil
	case RunnerRamalama:
		return &ramalamaRunner{}, nil
	default:
		return nil, fmt.Errorf("unknown runner type: %s (valid options: docker, ramalama)", runnerType)
	}
}

// validateCommonPrerequisites checks prerequisites common to all runners.
func validateCommonPrerequisites(a app.App) error {
	// VM must be running
	if !a.Active() {
		return fmt.Errorf("%s is not running", config.CurrentProfile().DisplayName)
	}

	// check runtime is docker
	r, err := a.Runtime()
	if err != nil {
		return err
	}
	if r != docker.Name {
		return fmt.Errorf("'colima model' requires docker runtime, current runtime is %s\n"+
			"Start colima with: colima start --runtime docker --vm-type krunkit", r)

View on GitHub (pinned to c3a5f9184d)

Solutions

1. Pass exactly 'docker' or 'ramalama', matching the valid options quoted in the message
2. Check the flag/env value for typos and trailing whitespace or stray quotes
3. If you maintain a fork that adds a runner, extend the switch and the error's option list together

Example fix

// before
r, err := GetRunner(runnerType)

// after: reject at the parse boundary instead of deep in the factory
if !isValidRunnerType(runnerType) {
	return fmt.Errorf("unknown runner type: %s (valid options: docker, ramalama)", runnerType)
}
r, err := GetRunner(runnerType)

func isValidRunnerType(rt RunnerType) bool {
	switch rt {
	case RunnerDocker, RunnerRamalama:
		return true
	}
	return false
}

When it happens

Trigger: Calling GetRunner with any RunnerType other than the docker/ramalama constants: colima model --runner podman, a typo like 'dockerr', or a variable that was never set (empty string).

Common situations: Users guessing runner names borrowed from other tools (podman); automation passing values from a mismatched colima version; whitespace or quotes in interpolated values.

Related errors

• %s is not running
• setup cancelled
• invalid downloader %q: must be one of %s, %s
• dependency check failed for VM: %w
• error retrieving current runtime: empty value

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