hashicorp/nomad · error

invalid bridge_network_subnet: %w

Error message

invalid bridge_network_subnet: %w

What it means

Nomad's convertClientConfig validates the client's bridge_network_subnet setting by parsing it with net.ParseCIDR. If the value is not a valid CIDR (e.g. missing prefix length or malformed IP), the parse error is wrapped in this error and agent startup (or reload) aborts.

Source

Thrown at command/agent/agent.go:1113

		// Default no_host_uuid to true
		conf.NoHostUUID = true
	}

	// Setup the ACLs
	conf.ACLEnabled = agentConfig.ACL.Enabled
	conf.ACLTokenTTL = agentConfig.ACL.TokenTTL
	conf.ACLPolicyTTL = agentConfig.ACL.PolicyTTL
	conf.ACLRoleTTL = agentConfig.ACL.RoleTTL

	// Setup networking configuration
	conf.CNIPath = agentConfig.Client.CNIPath
	conf.CNIConfigDir = agentConfig.Client.CNIConfigDir
	conf.BridgeNetworkName = agentConfig.Client.BridgeNetworkName
	ipv4Subnet := agentConfig.Client.BridgeNetworkSubnet
	if ipv4Subnet != "" {
		ip, _, err := net.ParseCIDR(ipv4Subnet)
		if err != nil {
			return nil, fmt.Errorf("invalid bridge_network_subnet: %w", err)
		}
		// it's a valid IP, so now make sure it is ipv4
		if ip.To4() == nil {
			return nil, fmt.Errorf("invalid bridge_network_subnet: not an IPv4 address: %s", ipv4Subnet)
		}
		conf.BridgeNetworkAllocSubnet = ipv4Subnet
	}
	ipv6Subnet := agentConfig.Client.BridgeNetworkSubnetIPv6
	if ipv6Subnet != "" {
		ip, _, err := net.ParseCIDR(ipv6Subnet)
		if err != nil {
			return nil, fmt.Errorf("invalid bridge_network_subnet_ipv6: %w", err)
		}
		// it's valid, so now make sure it's *not* ipv4
		if ip.To4() != nil {
			return nil, fmt.Errorf("invalid bridge_network_subnet_ipv6: not an IPv6 address: %s", ipv6Subnet)
		}
		conf.BridgeNetworkAllocSubnetIPv6 = ipv6Subnet

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Fix client.bridge_network_subnet in the agent config to a valid IPv4 CIDR, e.g. '10.0.0.0/24'
2. Verify with `nomad agent -config ... -verify-only` or run the value through a CIDR validator before deploying
3. If you only have a plain IP, add the desired prefix length, e.g. '192.168.1.10' -> '192.168.1.10/32' or the subnet mask form

Example fix

// before
client {
  bridge_network_subnet = "10.0.0.0"
}
// after
client {
  bridge_network_subnet = "10.0.0.0/24"
}

subnet := "10.0.0.0/24"
if _, _, err := net.ParseCIDR(subnet); err != nil {
    return fmt.Errorf("bridge_network_subnet must be a valid CIDR: %w", err)
}

func isValidIPv4CIDR(s string) bool {
    ip, _, err := net.ParseCIDR(s)
    return err == nil && ip.To4() != nil
}

When it happens

Trigger: Setting client.bridge_network_subnet in the agent config to a string that net.ParseCIDR cannot parse, such as '10.0.0.0/24x', '10.0.0.0' (no /prefix), or an empty/garbage value; triggered during agent start, initial clientConfig build, or SIGHUP reload via handleReload.

Common situations: Typos in the config file, omitting the /prefix suffix, copy-pasting a plain IP instead of a CIDR block, or templating tools rendering an invalid value into the HCL/JSON config.

Related errors

• invalid bridge_network_subnet_ipv6: %w
• network namespace already exists but was misconfigured
• network already configured but not found in state
• no CNI network config found
• failed to parse config:

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/9df3aaa88887f763. Report an issue: GitHub.