the service-level mac_address should have the same value as

Error message

the service-level mac_address should have the same value as network %s

What it means

Error "the service-level mac_address should have the same value as network %s" thrown in docker/compose.

Source

Thrown at pkg/compose/create.go:458

// also deprecates the container-wide mac_address field. Thus, this method will validate service config and mutate the
// passed mainNw to provide backward-compatibility whenever possible.
//
// It returns the container-wide MAC address, but this value will be kept empty for newer API versions.
func (s *composeService) prepareContainerMACAddress(service types.ServiceConfig, mainNw *types.ServiceNetworkConfig, nwName string) error {
	// Engine API 1.44 added support for endpoint-specific MAC address and now returns a warning when a MAC address is
	// set in container.Config. Thus, we have to jump through a number of hoops:
	//
	// 1. Top-level mac_address and main endpoint's MAC address should be the same ;
	// 2. If supported by the API, top-level mac_address should be migrated to the main endpoint and container.Config
	//    should be kept empty ;
	// 3. Otherwise, the endpoint mac_address should be set in container.Config and no other endpoint-specific
	//    mac_address can be specified. If that's the case, use top-level mac_address ;
	//
	// After that, if an endpoint mac_address is set, it's either user-defined or migrated by the code below, so
	// there's no need to check for API version in defaultNetworkSettings.
	macAddress := service.MacAddress
	if macAddress != "" && mainNw != nil && mainNw.MacAddress != "" && mainNw.MacAddress != macAddress {
		return fmt.Errorf("the service-level mac_address should have the same value as network %s", nwName)
	}
	if mainNw != nil && mainNw.MacAddress == "" {
		mainNw.MacAddress = macAddress
	}
	return nil
}

func getAliases(project *types.Project, service types.ServiceConfig, serviceIndex int, cfg *types.ServiceNetworkConfig, useNetworkAliases bool) []string {
	aliases := []string{getContainerName(project.Name, service, serviceIndex)}
	if useNetworkAliases {
		aliases = append(aliases, service.Name)
		if cfg != nil {
			aliases = append(aliases, cfg.Aliases...)
		}
	}
	return aliases
}

View on GitHub (pinned to ddc4b044b6)

Solutions

Set mac_address only in one place: either at service level or under the network configuration, with the same value.
Remove the service-level mac_address if the network-level one is authoritative.

When it happens

Trigger: The service-level mac_address conflicts with the mac_address set for that service inside a network-specific configuration; both must match.

Common situations: mac_address is set at the service level and again under networks.<name> with a different value for the same service.

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