{"record":{"id":"6120f7c7529f49d0","repo":"hashicorp/nomad","slug":"invalid-bridge-network-subnet-not-an-ipv4-address","errorCode":null,"errorMessage":"invalid bridge_network_subnet: not an IPv4 address: %s","messagePattern":"invalid bridge_network_subnet: not an IPv4 address: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"command/agent/agent.go","lineNumber":1117,"sourceCode":"\t// Setup the ACLs\n\tconf.ACLEnabled = agentConfig.ACL.Enabled\n\tconf.ACLTokenTTL = agentConfig.ACL.TokenTTL\n\tconf.ACLPolicyTTL = agentConfig.ACL.PolicyTTL\n\tconf.ACLRoleTTL = agentConfig.ACL.RoleTTL\n\n\t// Setup networking configuration\n\tconf.CNIPath = agentConfig.Client.CNIPath\n\tconf.CNIConfigDir = agentConfig.Client.CNIConfigDir\n\tconf.BridgeNetworkName = agentConfig.Client.BridgeNetworkName\n\tipv4Subnet := agentConfig.Client.BridgeNetworkSubnet\n\tif ipv4Subnet != \"\" {\n\t\tip, _, err := net.ParseCIDR(ipv4Subnet)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"invalid bridge_network_subnet: %w\", err)\n\t\t}\n\t\t// it's a valid IP, so now make sure it is ipv4\n\t\tif ip.To4() == nil {\n\t\t\treturn nil, fmt.Errorf(\"invalid bridge_network_subnet: not an IPv4 address: %s\", ipv4Subnet)\n\t\t}\n\t\tconf.BridgeNetworkAllocSubnet = ipv4Subnet\n\t}\n\tipv6Subnet := agentConfig.Client.BridgeNetworkSubnetIPv6\n\tif ipv6Subnet != \"\" {\n\t\tip, _, err := net.ParseCIDR(ipv6Subnet)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"invalid bridge_network_subnet_ipv6: %w\", err)\n\t\t}\n\t\t// it's valid, so now make sure it's *not* ipv4\n\t\tif ip.To4() != nil {\n\t\t\treturn nil, fmt.Errorf(\"invalid bridge_network_subnet_ipv6: not an IPv6 address: %s\", ipv6Subnet)\n\t\t}\n\t\tconf.BridgeNetworkAllocSubnetIPv6 = ipv6Subnet\n\t}\n\tconf.BridgeNetworkHairpinMode = agentConfig.Client.BridgeNetworkHairpinMode\n\n\tfor _, hn := range agentConfig.Client.HostNetworks {","sourceCodeStart":1099,"sourceCodeEnd":1135,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/agent.go#L1099-L1135","documentation":"After net.ParseCIDR succeeds, convertClientConfig additionally requires bridge_network_subnet to be IPv4. If the parsed address has no IPv4 representation (ip.To4() == nil), i.e. an IPv6 CIDR was supplied, this error is returned and agent startup/reload fails.","triggerScenarios":"Setting client.bridge_network_subnet to an IPv6 CIDR such as 'fd00::/64' or '::1/128'; raised during agent start, clientConfig construction, or handleReload.","commonSituations":"Users intending to configure IPv6 bridge networking but placing the IPv6 subnet in bridge_network_subnet instead of bridge_network_subnet_ipv6; copy-paste from IPv6 documentation.","solutions":["Move the IPv6 value to client.bridge_network_subnet_ipv6","Set client.bridge_network_subnet to an IPv4 CIDR, e.g. '172.26.66.0/20'","If only IPv6 networking is desired, remove bridge_network_subnet entirely and configure only the IPv6 field"],"exampleFix":"// before\nclient {\n  bridge_network_subnet = \"fd00::/64\"\n}\n// after\nclient {\n  bridge_network_subnet = \"172.26.66.0/20\"\n  bridge_network_subnet_ipv6 = \"fd00::/64\"\n}","handlingStrategy":"validation","validationCode":"subnet := \"172.26.66.0/20\"\nif ip, _, err := net.ParseCIDR(subnet); err != nil || ip.To4() == nil {\n    return fmt.Errorf(\"bridge_network_subnet must be an IPv4 CIDR\")\n}","typeGuard":"func isValidIPv4CIDR(s string) bool {\n    ip, _, err := net.ParseCIDR(s)\n    return err == nil && ip.To4() != nil\n}","tryCatchPattern":null,"preventionTips":["Never put IPv6 CIDRs in bridge_network_subnet; use bridge_network_subnet_ipv6","Run a dual-stack config checklist when enabling IPv6","Validate config with `nomad agent -verify-only`"],"tags":["nomad","config-validation","ipv4","ipv6"],"backgroundTag":"invalid-cidr-notation","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}