docker/compose · error

interface_name requires Docker Engine %s or later

Error message

interface_name requires Docker Engine %s or later

What it means

Error "interface_name requires Docker Engine %s or later" thrown in docker/compose.

Source

Thrown at pkg/compose/create.go:609

// defaultNetworkSettings determines the container.NetworkMode and corresponding network.NetworkingConfig (nil if not applicable).
func defaultNetworkSettings(project *types.Project,
	service types.ServiceConfig, serviceIndex int,
	links []string, useNetworkAliases bool,
	version string,
) (container.NetworkMode, *network.NetworkingConfig, error) {
	if service.NetworkMode != "" {
		return container.NetworkMode(service.NetworkMode), nil, nil
	}

	if len(project.Networks) == 0 {
		return network.NetworkNone, nil, nil
	}

	if versions.LessThan(version, apiVersion149) {
		for _, config := range service.Networks {
			if config != nil && config.InterfaceName != "" {
				return "", nil, fmt.Errorf("interface_name requires Docker Engine %s or later", DockerEngineV28_1)
			}
		}
	}

	serviceNetworks := service.NetworksByPriority()
	primaryNetworkKey := "default"
	if len(serviceNetworks) > 0 {
		primaryNetworkKey = serviceNetworks[0]
		serviceNetworks = serviceNetworks[1:]
	}

	primaryNetworkEndpoint, err := createEndpointSettings(project, service, serviceIndex, primaryNetworkKey, links, useNetworkAliases)
	if err != nil {
		return "", nil, err
	}
	if primaryNetworkEndpoint.MacAddress.String() == "" {
		primaryNetworkEndpoint.MacAddress, err = parseMACAddr(service.MacAddress)
		if err != nil {

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Upgrade the Docker Engine to the required version or later to use interface_name.
2. Remove the interface_name field from the network configuration if upgrading is not possible.

When it happens

Trigger: A network configuration uses 'interface_name', which requires a Docker Engine version newer than the one currently connected.

Common situations: The Docker daemon is older than the minimum version supporting interface_name; upgrade the engine or remove the option.

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