{"record":{"id":"af034991977beb05","repo":"cloudflare/cloudflared","slug":"ipv6-bind-address-is-specified-but-edge-ip-versio","errorCode":null,"errorMessage":"IPv6 bind address is specified, but edge-ip-version is IPv4","messagePattern":"IPv6 bind address is specified, but edge-ip-version is IPv4","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/cloudflared/tunnel/configuration.go","lineNumber":350,"sourceCode":"\t\treturn err\n\t}\n\t_ = listener.Close()\n\treturn nil\n}\n\nfunc adjustIPVersionByBindAddress(ipVersion allregions.ConfigIPVersion, ip net.IP) (allregions.ConfigIPVersion, error) {\n\tif ip == nil {\n\t\treturn ipVersion, nil\n\t}\n\t// https://pkg.go.dev/net#IP.To4: \"If ip is not an IPv4 address, To4 returns nil.\"\n\tif ip.To4() != nil {\n\t\tif ipVersion == allregions.IPv6Only {\n\t\t\treturn allregions.IPv4Only, fmt.Errorf(\"IPv4 bind address is specified, but edge-ip-version is IPv6\")\n\t\t}\n\t\treturn allregions.IPv4Only, nil\n\t} else {\n\t\tif ipVersion == allregions.IPv4Only {\n\t\t\treturn allregions.IPv6Only, fmt.Errorf(\"IPv6 bind address is specified, but edge-ip-version is IPv4\")\n\t\t}\n\t\treturn allregions.IPv6Only, nil\n\t}\n}\n\nfunc newICMPRouter(c *cli.Context, logger *zerolog.Logger) (ingress.ICMPRouterServer, error) {\n\tipv4Src, ipv6Src, err := determineICMPSources(c, logger)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\ticmpRouter, err := ingress.NewICMPRouter(ipv4Src, ipv6Src, logger, icmpFunnelTimeout)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\treturn icmpRouter, nil\n}\n","sourceCodeStart":332,"sourceCodeEnd":368,"githubUrl":"https://github.com/cloudflare/cloudflared/blob/2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f/cmd/cloudflared/tunnel/configuration.go#L332-L368","documentation":"adjustIPVersionByBindAddress reconciles the --edge-ip-version flag with the bind address configured for cloudflared. When the bind address is an IPv6 address (or the config resolves to IPv6-only) but edge-ip-version is set to IPv4, the function returns IPv6Only and this error because the two settings are contradictory. Cloudflared cannot connect to the edge over IPv4 while bound to an IPv6 local address.","triggerScenarios":"Running `cloudflared tunnel` with `--edge-ip-version 4` while the `--bind-address` (or equivalent config field) points at an IPv6 address such as `::` or `::1`, or while the resolved region set is IPv6Only.","commonSituations":"Operators copy an IPv6 bind address from a dual-stack host into a config file that also pins edge-ip-version to 4; automation scripts set edge-ip-version for IPv4-only networks but inherit a stale IPv6 bind address; Kubernetes/host networking defaults change underneath the config.","solutions":["Change --edge-ip-version to 6 (or remove it) so it matches the IPv6 bind address","Change the bind address to an IPv4 address (e.g. 0.0.0.0) to match edge-ip-version=4","Remove the explicit bind address so cloudflared auto-selects a source matching edge-ip-version"],"exampleFix":"// before (config.yml)\nedge-ip-version: 4\nprotocol: quic\nbind-address: \"[::]:0\"\n\n// after\nedge-ip-version: 6\nprotocol: quic\nbind-address: \"[::]:0\"","handlingStrategy":"validation","validationCode":"ipV4, _ := netip.ParseAddr(bindAddr)\nedgeIsV4 := edgeIPVersion == \"4\"\nif ipV4.Is6() && edgeIsV4 {\n    return fmt.Errorf(\"bind address %s is IPv6 but edge-ip-version is 4\", bindAddr)\n}","typeGuard":"func isIPv6Bind(addr string) bool { a, err := netip.ParseAddr(addr); return err == nil && a.Is6() }","tryCatchPattern":"if err := adjustIPVersionByBindAddress(ipVersion, bindAddr); err != nil {\n    logger.Error().Err(err).Msg(\"conflicting edge-ip-version and bind-address\")\n    return err\n}","preventionTips":["Keep edge-ip-version and bind-address in one place in your config so they are reviewed together","In automation, derive one setting from the other instead of hardcoding both","Test config changes with `cloudflared tunnel ingress validate`-style dry checks before deploying"],"tags":["network","ipv6","configuration","cli"],"backgroundTag":"conflicting-config-options","analyzedSha":"2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f","analyzedAt":"2026-09-06T04:14:33.757Z","contentChangedAt":"2026-09-06T04:14:33.757Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}