cloudflare/cloudflared · error

invalid value for edge-ip-version: %s

Error message

invalid value for edge-ip-version: %s

What it means

parseConfigIPVersion maps the `edge-ip-version` setting to one of IPv4Only/IPv6Only/Auto; any value outside {"4","6","auto"} (including an empty string) is invalid, so runPrechecks/prepareTunnelConfig fail before connecting.

Source

Thrown at cmd/cloudflared/tunnel/configuration.go:306

	}
	return period, nil
}

func isRunningFromTerminal() bool {
	return term.IsTerminal(int(os.Stdout.Fd())) // nolint:gosec
}

// ParseConfigIPVersion returns the IP version from possible expected values from config
func parseConfigIPVersion(version string) (v allregions.ConfigIPVersion, err error) {
	switch version {
	case "4":
		v = allregions.IPv4Only
	case "6":
		v = allregions.IPv6Only
	case "auto":
		v = allregions.Auto
	default: // unspecified or invalid
		err = fmt.Errorf("invalid value for edge-ip-version: %s", version)
	}
	return
}

func parseConfigBindAddress(ipstr string) (net.IP, error) {
	// Unspecified - it's fine
	if ipstr == "" {
		return nil, nil
	}
	ip := net.ParseIP(ipstr)
	if ip == nil {
		return nil, fmt.Errorf("invalid value for edge-bind-address: %s", ipstr)
	}
	return ip, nil
}

func testIPBindable(ip net.IP) error {
	// "Unspecified" = let OS choose, so always bindable

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Set edge-ip-version to exactly `4`, `6`, or `auto`.
2. Remove the empty/invalid key from the config file or drop the flag to default to auto behavior where applicable.
3. In templated deployments, guard so an empty variable omits the flag rather than passing an empty string.

Example fix

// before
edge-ip-version: ipv4
// after
edge-ip-version: 4

// shell: accept only 4, 6, auto
v="${EDGE_IP_VERSION:-auto}"
[[ "$v" =~ ^(4|6|auto)$ ]] || { echo "edge-ip-version must be 4|6|auto"; exit 1; }

When it happens

Trigger: Setting `--edge-ip-version` (or config `edge-ip-version:`) to values like "ipv4", "v4", "both", or leaving an empty value that still reaches the parser (e.g. `edge-ip-version: ""` in config).

Common situations: Guessing the accepted values from documentation wording; YAML config retaining an empty key after editing; automation templating an unset variable into the flag.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• No configuration file was found. Please create one, or use t
• ErrNoIngressRulesCLI
• Did not receive final destination from client. The --destina
• configuration file %s must contain entries for the tunnel to
• possible conflicting configuration in %[1]s and %[2]s. Eithe

AI-assisted analysis of cloudflare/cloudflared@2253eeeb25 (2026-09-06). Data as JSON: /api/errors/bf2576698878f81b. Report an issue: GitHub.