{"record":{"id":"95e6fb1fceca47eb","repo":"abiosoft/colima","slug":"gateway-q-is-not-ipv4","errorCode":null,"errorMessage":"gateway %q is not IPv4","messagePattern":"gateway %q is not IPv4","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"config/configmanager/configmanager.go","lineNumber":139,"sourceCode":"func LoadInstance() (config.Config, error) {\n\treturn LoadFrom(config.CurrentProfile().StateFile())\n}\n\n// Teardown deletes the config.\nfunc Teardown() error {\n\tdir := config.CurrentProfile().ConfigDir()\n\tif _, err := os.Stat(dir); err == nil {\n\t\treturn os.RemoveAll(dir)\n\t}\n\treturn nil\n}\n\n// Validates that gateway is a valid IPv4 address and that the last octet is “2”.\n// Lima uses the last octet as 2 for gateways.\nfunc validateGatewayAddress(gateway net.IP) error {\n\tip4 := gateway.To4()\n\tif ip4 == nil {\n\t\treturn fmt.Errorf(\"gateway %q is not IPv4\", gateway)\n\t}\n\n\t// Check last octet\n\tif ip4[3] != 2 {\n\t\treturn fmt.Errorf(\"the last octet of gateway %q is not 2\", gateway)\n\t}\n\n\treturn nil\n}\n\n// validateMounts ensures mount paths do not contain spaces, which are not\n// supported by the underlying Lima runtime and otherwise fail silently.\n// See https://github.com/abiosoft/colima/issues/1471.\nfunc validateMounts(mounts []config.Mount) error {\n\tfor _, m := range mounts {\n\t\tfor _, p := range []string{m.Location, m.MountPoint} {\n\t\t\tif strings.Contains(p, \" \") {\n\t\t\t\treturn fmt.Errorf(\"mount path with spaces is not supported by the underlying Lima runtime: %q\", p)","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/abiosoft/colima/blob/c3a5f9184d83a197184f897a9f07eb3c01b3bc88/config/configmanager/configmanager.go#L121-L157","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set gatewayAddress to an IPv4 literal ending in .2, e.g. 192.168.104.2","Remove the gatewayAddress key if a custom gateway is not required","Confirm the value is a bare IP literal, not a hostname, range, or CIDR"],"exampleFix":"# before\nnetwork:\n  gatewayAddress: fd00::2\n\n# after\nnetwork:\n  gatewayAddress: 192.168.104.2","handlingStrategy":"validation","validationCode":"if c.Network.GatewayAddress != nil {\n    if c.Network.GatewayAddress.To4() == nil {\n        // replace with an IPv4 literal ending in .2 before validating\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := configmanager.ValidateConfig(c); err != nil {\n    if strings.HasPrefix(err.Error(), \"gateway\") && strings.HasSuffix(err.Error(), \"is not IPv4\") {\n        // the gateway must be an IPv4 literal; fix network.gatewayAddress\n    }\n}","preventionTips":["Always configure gatewayAddress as an IPv4 literal ending in .2","Do not paste IPv6 or hostname values into gatewayAddress","Omit gatewayAddress when defaults are acceptable"],"tags":["config","validation","network","ipv4"],"backgroundTag":null,"analyzedSha":"c3a5f9184d83a197184f897a9f07eb3c01b3bc88","analyzedAt":"2026-08-15T18:58:08.334Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}