{"record":{"id":"326c82338ac0b904","repo":"cloudflare/cloudflared","slug":"ipv4-bind-address-is-specified-but-edge-ip-versio","errorCode":null,"errorMessage":"IPv4 bind address is specified, but edge-ip-version is IPv6","messagePattern":"IPv4 bind address is specified, but edge-ip-version is IPv6","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"cmd/cloudflared/tunnel/configuration.go","lineNumber":345,"sourceCode":"\t}\n\n\taddr := &net.UDPAddr{IP: ip, Port: 0}\n\tlistener, err := net.ListenUDP(\"udp\", addr)\n\tif err != nil {\n\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 {","sourceCodeStart":327,"sourceCodeEnd":363,"githubUrl":"https://github.com/cloudflare/cloudflared/blob/2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f/cmd/cloudflared/tunnel/configuration.go#L327-L363","documentation":"adjustIPVersionByBindAddress enforces consistency between `edge-ip-version` and `edge-bind-address`: an IPv4 bind address with edge-ip-version=6 (or the reverse) is contradictory. The function corrects the version and returns this error as a warning condition; prepareTunnelConfig logs it and proceeds with the corrected value.","triggerScenarios":"Setting `--edge-ip-version 6` together with an IPv4 `--edge-bind-address` (e.g. 0.0.0.0), or `--edge-ip-version 4` with an IPv6 bind address.","commonSituations":"Configs copied between dual-stack and single-stack hosts; operators forcing IPv6 edge preference while a legacy IPv4 bind address remains in config.","solutions":["Align the two settings: use an IPv6 bind address with edge-ip-version 6, or an IPv4 address with 4.","Set edge-ip-version to `auto` so the bind address family decides.","Note this is non-fatal: cloudflared logs \"Overriding edge-ip-version\" and continues with the address's family — silence it by fixing the mismatch."],"exampleFix":"// before\nedge-ip-version: 6\nedge-bind-address: 0.0.0.0\n// after\nedge-ip-version: 6\nedge-bind-address: \"::\"","handlingStrategy":"validation","validationCode":"// shell: keep ip-version and bind address family consistent\nv=\"${EDGE_IP_VERSION:-auto}\"; a=\"${EDGE_BIND_ADDR:-}\"\nif [ -n \"$a\" ]; then\n  case \"$a\" in *:*) fam=6 ;; *) fam=4 ;; esac\n  [ \"$v\" = auto ] || [ \"$v\" = \"$fam\" ] || EDGE_IP_VERSION=\"$fam\"\nfi","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Derive edge-ip-version from the bind address family, or leave it as auto.","Audit configs for leftover bind addresses after host migrations.","Watch for the 'Overriding edge-ip-version' warning in logs — it flags this mismatch."],"tags":["configuration","network","ip-version"],"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"}