abiosoft/colima · error

gateway %q is not IPv4

Error message

gateway %q is not IPv4

What it means

validateGatewayAddress requires network.gatewayAddress to be an IPv4 address. It calls net.IP.To4() and fails when the address has no IPv4 representation: IPv6 addresses (including IPv4-mapped forms that fail conversion) or values that never parsed into a valid net.IP. The offending address is printed with %q.

Source

Thrown at config/configmanager/configmanager.go:139

func LoadInstance() (config.Config, error) {
	return LoadFrom(config.CurrentProfile().StateFile())
}

// Teardown deletes the config.
func Teardown() error {
	dir := config.CurrentProfile().ConfigDir()
	if _, err := os.Stat(dir); err == nil {
		return os.RemoveAll(dir)
	}
	return nil
}

// Validates that gateway is a valid IPv4 address and that the last octet is “2”.
// Lima uses the last octet as 2 for gateways.
func validateGatewayAddress(gateway net.IP) error {
	ip4 := gateway.To4()
	if ip4 == nil {
		return fmt.Errorf("gateway %q is not IPv4", gateway)
	}

	// Check last octet
	if ip4[3] != 2 {
		return fmt.Errorf("the last octet of gateway %q is not 2", gateway)
	}

	return nil
}

// validateMounts ensures mount paths do not contain spaces, which are not
// supported by the underlying Lima runtime and otherwise fail silently.
// See https://github.com/abiosoft/colima/issues/1471.
func validateMounts(mounts []config.Mount) error {
	for _, m := range mounts {
		for _, p := range []string{m.Location, m.MountPoint} {
			if strings.Contains(p, " ") {
				return fmt.Errorf("mount path with spaces is not supported by the underlying Lima runtime: %q", p)

View on GitHub (pinned to c3a5f9184d)

Solutions

1. Set gatewayAddress to an IPv4 literal ending in .2, e.g. 192.168.104.2
2. Remove the gatewayAddress key if a custom gateway is not required
3. Confirm the value is a bare IP literal, not a hostname, range, or CIDR

Example fix

# before
network:
  gatewayAddress: fd00::2

# after
network:
  gatewayAddress: 192.168.104.2

if c.Network.GatewayAddress != nil {
    if c.Network.GatewayAddress.To4() == nil {
        // replace with an IPv4 literal ending in .2 before validating
    }
}

if err := configmanager.ValidateConfig(c); err != nil {
    if strings.HasPrefix(err.Error(), "gateway") && strings.HasSuffix(err.Error(), "is not IPv4") {
        // the gateway must be an IPv4 literal; fix network.gatewayAddress
    }
}

When it happens

Trigger: Setting network.gatewayAddress to an IPv6 literal such as fd00::2 in colima.yaml; a value with a zone index; any string that yaml decodes into a net.IP which To4() cannot represent.

Common situations: Copying dual-stack or IPv6 network examples into config; enterprise environments documented in IPv6; mistaking the field for one that accepts hostnames or CIDR notation.

Related errors

• the last octet of gateway %q is not 2
• error in config file: %w
• error in config: %w
• invalid mountType: '%s'
• vmType 'krunkit' is only available on macOS with Apple Silic

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