hashicorp/nomad · error

invalid bridge_network_subnet_ipv6: %w

Error message

invalid bridge_network_subnet_ipv6: %w

What it means

convertClientConfig parses client.bridge_network_subnet_ipv6 with net.ParseCIDR; if parsing fails the wrapped error is returned as this message, aborting agent start or reload. The field must be a syntactically valid CIDR.

Source

Thrown at command/agent/agent.go:1125

	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
	}
	conf.BridgeNetworkHairpinMode = agentConfig.Client.BridgeNetworkHairpinMode

	for _, hn := range agentConfig.Client.HostNetworks {
		conf.HostNetworks[hn.Name] = hn
	}
	conf.BindWildcardDefaultHostNetwork = agentConfig.Client.BindWildcardDefaultHostNetwork

	if agentConfig.Client.NomadServiceDiscovery != nil {
		conf.NomadServiceDiscovery = *agentConfig.Client.NomadServiceDiscovery
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Correct client.bridge_network_subnet_ipv6 to a valid IPv6 CIDR, e.g. 'fd00::/64'
2. Ensure the value includes a prefix length (/n)
3. Validate the config with `nomad agent -verify-only` before restart

Example fix

// before
client {
  bridge_network_subnet_ipv6 = "fd00::"
}
// after
client {
  bridge_network_subnet_ipv6 = "fd00::/64"
}

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

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

When it happens

Trigger: client.bridge_network_subnet_ipv6 set to an unparsable string: missing prefix ('fd00::'), malformed address, or garbage/templating artifact; raised via clientConfig, agent start, or handleReload.

Common situations: Typos in the HCL/JSON config, omitting /prefix, shell/env templating rendering empty or partial values, mixing up the IPv4 and IPv6 field names.

Related errors

• invalid bridge_network_subnet: %w
• invalid bridge_network_subnet: not an IPv4 address: %s
• invalid bridge_network_subnet_ipv6: not an IPv6 address: %s
• failed to parse ipv6_address %q: %v
• failed to parse config:

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