hashicorp/nomad · error

failed to parse ipv4_address %q: %v

Error message

failed to parse ipv4_address %q: %v

What it means

When ipv4_address (or ipv6_address) is set in the docker driver config, the value is parsed with netip.ParseAddr before being placed into the Docker EndpointIPAMConfig. A string that is not a valid IP literal is rejected with this wrapped parse error.

Source

Thrown at drivers/docker/driver.go:1560

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

	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 {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Provide a bare, valid IPv4 address with no prefix or hostname, e.g. 10.0.0.5
2. Remove any /24-style CIDR suffix from ipv4_address
3. Ensure the value is a plain IP string without quotes/whitespace issues after template rendering

Example fix

// before
driver {
  docker {
    ipv4_address = "10.0.0.5/24"
  }
}
// after
driver {
  docker {
    ipv4_address = "10.0.0.5"
  }
}

if cfg.IPv4Address != "" {
  if _, err := netip.ParseAddr(cfg.IPv4Address); err != nil {
    return fmt.Errorf("ipv4_address must be a bare IP, got %q", cfg.IPv4Address)
  }
}

func validIPv4(s string) bool { a, err := netip.ParseAddr(s); return err == nil && a.Is4() }

err := client.StartTask(task); if err != nil && strings.Contains(err.Error(), "failed to parse ipv4_address") { logBadIP(cfg.IPv4Address) }

When it happens

Trigger: StartTask -> createContainerConfig sees driverConfig.IPv4Address != "" and netip.ParseAddr fails (e.g. a hostname, a CIDR suffix like 10.0.0.5/24, or a malformed octet).

Common situations: Passing a Docker network name or container hostname instead of an IP; including a /prefix that Docker's ipv4_address does not accept here; IPv4 text placed in the ipv6 field or vice versa; trailing whitespace/quotes 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

• Port %q not found, check network block
• invalid value for cpu_cfs_period
• failed to parse security_opt configuration: %v
• failed to parse ulimit configuration: %v
• Trying to map ports but no network interface is available

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