What causes "invalid edge-bind-address %s: %v" in cloudflare/cloudflared?

Remove the `edge-bind-address` setting to let the OS choose the appropriate local address.

invalid edge-bind-address %s: %v

Error message

invalid edge-bind-address %s: %v

What it means

The edge-bind-address flag was parsed successfully but the address cannot actually be bound (testIPBindable opens a listener to verify). The library throws this so tunnel startup fails fast instead of failing later at connection time.

Source

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

			edgeTLSConfig.NextProtos = tlsSettings.NextProtos
		}
		edgeTLSConfigs[p] = edgeTLSConfig
	}

	gracePeriod, err := gracePeriod(c)
	if err != nil {
		return nil, nil, err
	}
	edgeIPVersion, err := parseConfigIPVersion(c.String(flags.EdgeIpVersion))
	if err != nil {
		return nil, nil, err
	}
	edgeBindAddr, err := parseConfigBindAddress(c.String(flags.EdgeBindAddress))
	if err != nil {
		return nil, nil, err
	}
	if err := testIPBindable(edgeBindAddr); err != nil {
		return nil, nil, fmt.Errorf("invalid edge-bind-address %s: %v", edgeBindAddr, err)
	}
	edgeIPVersion, err = adjustIPVersionByBindAddress(edgeIPVersion, edgeBindAddr)
	if err != nil {
		// This is not a fatal error, we just overrode edgeIPVersion
		log.Warn().Str("edgeIPVersion", edgeIPVersion.String()).Err(err).Msg("Overriding edge-ip-version")
	}

	region := c.String(flags.Region)
	endpoint := namedTunnel.Credentials.Endpoint
	var resolvedRegion string
	// set resolvedRegion to either the region passed as argument
	// or to the endpoint in the credentials.
	// Region and endpoint are interchangeable
	if region != "" && endpoint != "" {
		return nil, nil, fmt.Errorf("region provided with a token that has an endpoint")
	} else if region != "" {
		resolvedRegion = region
	} else if endpoint != "" {

View on GitHub (pinned to 2253eeeb25)

Solutions

Remove the `edge-bind-address` setting to let the OS choose the appropriate local address.
Set it to an IP that exists on the host (`ip addr` / `ifconfig`) and is bindable.
In containers, prefer 0.0.0.0/:: or the pod IP; verify with `ip addr` inside the container.

Example fix

// before (config.yml)
edge-bind-address: 10.0.0.99
// after
# edge-bind-address removed; OS chooses the local address

Defensive patterns

Strategy: validation

Validate before calling

// shell: ensure the bind address exists on this host
ip="10.0.0.5"
ip -o addr show | grep -qw "$ip" || { echo "$ip not on any interface"; exit 1; }

Prevention

Only set edge-bind-address when you know the exact local interface IP.
Omit the setting in containers unless the pod IP is known at start time.
Test config changes with `cloudflared tunnel --config ... run` in a staging host first.

When it happens

Trigger: Setting `--edge-bind-address` to an IP not present on any local interface, an address in use without SO_REUSE options, or a privileged/port-conflicted address, then running `cloudflared tunnel run`.

Common situations: Copying a config from another host whose interface IP differs; running in containers/Kubernetes where the pod has no route to the specified IP; specifying an IPv6 address on an IPv4-only host.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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