hashicorp/nomad · error

failed to parse mac_address %q: %v

Error message

failed to parse mac_address %q: %v

What it means

The Docker driver parses driverConfig.MacAddress with net.ParseMAC before attaching it to the container's networking config. If the MAC address string is not in a valid format (e.g. aa:bb:cc:dd:ee:ff, aa-bb-cc-dd-ee-ff, or aa.bb.cc.dd.ee.ff), this error is returned and the task fails to start.

Source

Thrown at drivers/docker/driver.go:1579

			}
			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): {},
				},
			}
		}
		networkingConfig.EndpointsConfig[string(hostConfig.NetworkMode)].MacAddress = networkapi.HardwareAddr(mac)

		logger.Debug("setting container mac address", "mac_address", driverConfig.MacAddress)
	}

	if driverConfig.Healthchecks.Disabled() {
		// Override any image-supplied health-check with disable sentinel.
		// https://github.com/docker/engine-api/blob/master/types/container/config.go#L16
		config.Healthcheck = &containerapi.HealthConfig{Test: []string{"NONE"}}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Correct mac_address to a full 6-octet MAC with consistent separators, e.g. "aa:bb:cc:dd:ee:ff".
2. Trim whitespace and re-check with `echo '<value>' | grep -iE '^([0-9a-f]{2}[:-]){5}[0-9a-f]{2}$'`.
3. Ensure the address is unique on the target network to avoid later Docker conflicts.

Example fix

// before
config {
  mac_address = "aa-bb-cc-dd-ee"
}
// after
config {
  mac_address = "aa:bb:cc:dd:ee:ff"
}

import "net"
func validMAC(s string) bool { _, err := net.ParseMAC(s); return err == nil }
// check validMAC(cfg.MacAddress) before submitting

When it happens

Trigger: A task config sets mac_address to a string that net.ParseMAC rejects — wrong separators, wrong number of octets, non-hex characters, or an empty-but-whitespace value.

Common situations: Typos in job specs, mixing separator styles (aa:bb-cc:...), supplying only 5 octets, or copying a MAC with surrounding whitespace/quotes.

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

• host path must be set in configuration for devices
• failed to parse ipv6_address %q: %v
• failed to parse config:
• running container as ContainerAdmin is unsafe; change the co
• error decoding stats data: no reader body

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