hashicorp/nomad · error

invalid bridge_network_subnet_ipv6: not an IPv6 address: %s

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.

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)

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: %s
• invalid bridge_network_subnet_ipv6: %w
• failed to parse ipv6_address %q: %v
• failed to parse config:
• only one of cgroups_v1_override and cgroups_v2_override may

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