hashicorp/nomad · error

failed to parse ipv6_address %q: %v

Error message

failed to parse ipv6_address %q: %v

What it means

Nomad's Docker driver validates the task driver config's ipv6_address by parsing it with netip.ParseAddr before passing it to the Docker IPAM config. If the string is not a valid IP address (IPv4 or IPv6 syntax), createContainerConfig returns this error and the task fails to start.

Source

Thrown at drivers/docker/driver.go:1567

	if len(driverConfig.NetworkAliases) > 0 {
		networkingConfig.EndpointsConfig[string(hostConfig.NetworkMode)].Aliases = driverConfig.NetworkAliases
		logger.Debug("setting container network aliases", "network_mode", hostConfig.NetworkMode,
			"network_aliases", strings.Join(driverConfig.NetworkAliases, ", "))
	}

	if driverConfig.IPv4Address != "" || driverConfig.IPv6Address != "" {
		ipamConfig := &networkapi.EndpointIPAMConfig{}
		if driverConfig.IPv4Address != "" {
			ipv4, err := netip.ParseAddr(driverConfig.IPv4Address)
			if err != nil {
				return c, fmt.Errorf("failed to parse ipv4_address %q: %v", driverConfig.IPv4Address, err)
			}
			ipamConfig.IPv4Address = ipv4
		}
		if driverConfig.IPv6Address != "" {
			ipv6, err := netip.ParseAddr(driverConfig.IPv6Address)
			if err != nil {
				return c, fmt.Errorf("failed to parse ipv6_address %q: %v", driverConfig.IPv6Address, err)
			}
			ipamConfig.IPv6Address = ipv6
		}
		networkingConfig.EndpointsConfig[string(hostConfig.NetworkMode)].IPAMConfig = ipamConfig
		logger.Debug("setting container network configuration", "network_mode", hostConfig.NetworkMode,
			"ipv4_address", driverConfig.IPv4Address, "ipv6_address", driverConfig.IPv6Address)
	}

	if driverConfig.MacAddress != "" {
		mac, err := net.ParseMAC(driverConfig.MacAddress)
		if err != nil {
			return c, fmt.Errorf("failed to parse mac_address %q: %v", driverConfig.MacAddress, err)
		}

		if networkingConfig == nil {
			networkingConfig = &networkapi.NetworkingConfig{
				EndpointsConfig: map[string]*networkapi.EndpointSettings{
					string(hostConfig.NetworkMode): {},

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Fix ipv6_address in the task's docker driver config to a valid bare IP literal, e.g. "2001:db8::1" (no prefix length, no hostname).
2. Validate locally with `nomad job inspect` or by running `python3 -c "import ipaddress; ipaddress.ip_address('<value>')"` before deploying.
3. If you actually need a subnet, that belongs in the network block's CIDR, not in ipv6_address.

Example fix

// before
driver = "docker"
config {
  ipv6_address = "2001:db8::/64"
}
// after
config {
  ipv6_address = "2001:db8::1"
}

import "netip"
func validIPv6(s string) bool { a, err := netip.ParseAddr(s); return err == nil && a.Is6() }
// check validIPv6(cfg.IPv6Address) before submitting the job

When it happens

Trigger: A task's docker driver config sets ipv6_address to a malformed value (e.g. missing colons, hostname, '2001:db8::/64' with a prefix length, or an IPv4-mapped typo) and StartTask calls createContainerConfig.

Common situations: Typos in job files, pasting a CIDR prefix instead of a bare address, using a hostname where an IP literal is required, or quoting/whitespace artifacts from templating.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• invalid bridge_network_subnet: not an IPv4 address: %s
• invalid bridge_network_subnet_ipv6: %w
• invalid bridge_network_subnet_ipv6: not an IPv6 address: %s
• host path must be set in configuration for devices
• failed to parse mac_address %q: %v

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