hashicorp/nomad · error

invalid bridge_network_subnet_ipv6: not an IPv6 address

Error message

invalid bridge_network_subnet_ipv6: not an IPv6 address: %s

What it means

convertClientConfig validates client { bridge_network_subnet_ipv6 }: the CIDR parses but the address is not IPv6, so the bridge network subnet for allocations cannot be configured and client startup fails.

Solutions

1. Move the IPv4 CIDR to client.bridge_network_subnet
2. Set client.bridge_network_subnet_ipv6 to a genuine IPv6 CIDR, e.g. 'fd00::/64'
3. Remove the ipv6 field if no IPv6 allocation is needed

Example fix

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

subnet := "fd00::/64"
if ip, _, err := net.ParseCIDR(subnet); err != nil || ip.To4() != nil {
    return fmt.Errorf("bridge_network_subnet_ipv6 must be an IPv6 CIDR")
}

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

When it happens

Trigger: Setting client.bridge_network_subnet_ipv6 to an IPv4 CIDR such as '10.0.0.0/24'; raised during agent start, clientConfig build, or SIGHUP reload.

Common situations: Swapping values between bridge_network_subnet and bridge_network_subnet_ipv6 when configuring dual-stack bridge networking; copy-paste mistakes.

Related errors

• invalid bridge_network_subnet: not an IPv4 address
• failed to parse ipv6_address
• invalid bridge_network_subnet_ipv6
• allow_caps configured with capabilities not supported by…
• auth method is missing

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

Appendix: source

Thrown at command/agent/agent.go:1129

		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
	}

	artifactConfig, err := clientconfig.ArtifactConfigFromAgent(agentConfig.Client.Artifact)
	if err != nil {
		return nil, fmt.Errorf("invalid artifact config: %v", err)
	}

View on GitHub (pinned to 482b49bf1a)