cloudflare/cloudflared · warning
IPv4 bind address is specified, but edge-ip-version is IPv6
Error message
IPv4 bind address is specified, but edge-ip-version is IPv6
What it means
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.
Source
Thrown at cmd/cloudflared/tunnel/configuration.go:345
}
addr := &net.UDPAddr{IP: ip, Port: 0}
listener, err := net.ListenUDP("udp", addr)
if err != nil {
return err
}
_ = listener.Close()
return nil
}
func adjustIPVersionByBindAddress(ipVersion allregions.ConfigIPVersion, ip net.IP) (allregions.ConfigIPVersion, error) {
if ip == nil {
return ipVersion, nil
}
// https://pkg.go.dev/net#IP.To4: "If ip is not an IPv4 address, To4 returns nil."
if ip.To4() != nil {
if ipVersion == allregions.IPv6Only {
return allregions.IPv4Only, fmt.Errorf("IPv4 bind address is specified, but edge-ip-version is IPv6")
}
return allregions.IPv4Only, nil
} else {
if ipVersion == allregions.IPv4Only {
return allregions.IPv6Only, fmt.Errorf("IPv6 bind address is specified, but edge-ip-version is IPv4")
}
return allregions.IPv6Only, nil
}
}
func newICMPRouter(c *cli.Context, logger *zerolog.Logger) (ingress.ICMPRouterServer, error) {
ipv4Src, ipv6Src, err := determineICMPSources(c, logger)
if err != nil {
return nil, err
}
icmpRouter, err := ingress.NewICMPRouter(ipv4Src, ipv6Src, logger, icmpFunnelTimeout)
if err != nil {View on GitHub (pinned to 2253eeeb25)
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.
Example fix
// before edge-ip-version: 6 edge-bind-address: 0.0.0.0 // after edge-ip-version: 6 edge-bind-address: "::"
Defensive patterns
Strategy: validation
Validate before calling
// shell: keep ip-version and bind address family consistent
v="${EDGE_IP_VERSION:-auto}"; a="${EDGE_BIND_ADDR:-}"
if [ -n "$a" ]; then
case "$a" in *:*) fam=6 ;; *) fam=4 ;; esac
[ "$v" = auto ] || [ "$v" = "$fam" ] || EDGE_IP_VERSION="$fam"
fi Prevention
- 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.
When it happens
Trigger: 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.
Common situations: Configs copied between dual-stack and single-stack hosts; operators forcing IPv6 edge preference while a legacy IPv4 bind address remains in config.
Related errors
- invalid edge-bind-address %s: %v
- invalid value for edge-ip-version: %s
- invalid value for edge-bind-address: %s
- IPv6 bind address is specified, but edge-ip-version is IPv4
- failed to resolve any edge address
AI-assisted analysis of cloudflare/cloudflared@2253eeeb25 (2026-09-06).
Data as JSON: /api/errors/326c82338ac0b904.
Report an issue: GitHub.