What causes "invalid port forwarder: '%s'" in abiosoft/colima?

Set portForwarder to exactly 'grpc', 'ssh', or 'none'

invalid port forwarder: '%s'

Error message

invalid port forwarder: '%s'

What it means

ValidateConfig checks portForwarder against the fixed allowlist {grpc, ssh, none}. Any other value, including case variants, whitespace, or names removed in earlier releases, is rejected with the value echoed. grpc and ssh select the host-guest forwarding mechanism; none disables port forwarding.

Source

Thrown at config/configmanager/configmanager.go:92

	if c.VMType == "qemu" {
		if err := util.AssertQemuImg(); err != nil {
			return fmt.Errorf("cannot use vmType: '%s', error: %w", c.VMType, err)
		}
	}
	if c.VMType == "krunkit" {
		if err := util.AssertKrunkit(); err != nil {
			return fmt.Errorf("cannot use vmType: '%s', error: %w", c.VMType, err)
		}
	}

	if c.DiskImage != "" {
		if strings.HasPrefix(c.DiskImage, "http://") || strings.HasPrefix(c.DiskImage, "https://") {
			return fmt.Errorf("cannot use diskImage: remote URLs not supported, only local files can be specified")
		}
	}

	if _, ok := validPortForwarders[c.PortForwarder]; !ok {
		return fmt.Errorf("invalid port forwarder: '%s'", c.PortForwarder)
	}

	if c.Network.GatewayAddress != nil {
		if err := validateGatewayAddress(c.Network.GatewayAddress); err != nil {
			return err
		}
	}

	if err := validateMounts(c.Mounts); err != nil {
		return err
	}

	return nil
}

// Load loads the config.
// Error is only returned if the config file exists but could not be loaded.
// No error is returned if the config file does not exist.

View on GitHub (pinned to c3a5f9184d)

Solutions

Set portForwarder to exactly 'grpc', 'ssh', or 'none'
Remove the key entirely to use the default forwarder for the release
Check the YAML value for trailing spaces or capitalized letters

Example fix

# before
portForwarder: gRPC

# after
portForwarder: grpc

Defensive patterns

Strategy: validation

Validate before calling

var validPortForwarders = map[string]bool{"grpc": true, "ssh": true, "none": true}
if !validPortForwarders[strings.TrimSpace(c.PortForwarder)] || c.PortForwarder != strings.TrimSpace(c.PortForwarder) {
    // fix the value before validation runs
}

Try / catch

if err := configmanager.ValidateConfig(c); err != nil {
    if strings.HasPrefix(err.Error(), "invalid port forwarder") {
        // show allowlist: grpc, ssh, none
    }
}

Prevention

Only use the exact lowercase values grpc, ssh, none
Set portForwarder via CLI flag to avoid hand-editing errors
Trim whitespace when generating configs programmatically

When it happens

Trigger: portForwarder set to values like 'gRPC', 'none ' with a trailing space, 'default', 'docker', or a forwarder name deprecated in an earlier colima release.

Common situations: Hand-editing colima.yaml; carrying old configs forward after colima upgrades renamed forwarders; copy-paste introducing capitalization or whitespace differences.

Related errors

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