docker/compose · error

invalid MAC address: %w

Error message

invalid MAC address: %w

What it means

A static MAC address configured for a service's network interface failed net.ParseMAC in parseMACAddr. Docker requires standard IEEE 802 forms (01:23:45:67:89:ab, 01-23-45-67-89-ab, or dot notation); anything else is rejected before the create call.

Source

Thrown at pkg/compose/create.go:1572

			auxAddress[auxName] = auxAddr
		}

	}
	return network.IPAMConfig{
		Subnet:     subNet,
		IPRange:    ipRange,
		Gateway:    gateway,
		AuxAddress: auxAddress,
	}, nil
}

func parseMACAddr(macAddress string) (network.HardwareAddr, error) {
	if macAddress == "" {
		return nil, nil
	}
	m, err := net.ParseMAC(macAddress)
	if err != nil {
		return nil, fmt.Errorf("invalid MAC address: %w", err)
	}
	return network.HardwareAddr(m), nil
}

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Use exactly 6 hex pairs for IPv4 NICs: 02:42:ac:11:00:02
2. Remove mac_address to let Docker assign one dynamically
3. Validate the value with a regex/parser before deploying

Example fix

# before
mac_address: "00:11:22:33:44"
# after
mac_address: "02:11:22:33:44:55"

if mac := svc.MacAddress; mac != "" { // or per-network entry
    if _, err := net.ParseMAC(string(mac)); err != nil {
        return fmt.Errorf("invalid mac_address %q: %w", mac, err)
    }
}

When it happens

Trigger: networks: {mac_address: 00:11:22:33:44} (5 groups), 'O0:11:...' with letter O, or an EUI-64 with wrong length under services.*.networks.<name>.mac_address.

Common situations: Odd group count, invalid hex chars, copy-paste with spaces; also per-interface mac_address on the service network config.

Related errors

• unsupported protocol for address: %s
• unsupported network: %s
• invalid subnet: %w
• invalid ip-range: %w
• invalid gateway address: %w

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/0b921d7b0e1e2845. Report an issue: GitHub.