docker/cli · error

invalid hostport binding (%s) for port (%d)

Error message

invalid hostport binding (%s) for port (%d)

What it means

Error "invalid hostport binding (%s) for port (%d)" thrown in docker/cli.

Source

Thrown at opts/swarmopts/port.go:172

func (p *PortOpt) Value() []swarm.PortConfig {
	return p.ports
}

// ConvertPortToPortConfig converts ports to the swarm type
func ConvertPortToPortConfig(
	portProto network.Port,
	portBindings map[nat.Port][]nat.PortBinding,
) ([]swarm.PortConfig, error) {
	ports := make([]swarm.PortConfig, 0, len(portBindings))
	for _, binding := range portBindings[nat.Port(portProto.String())] {
		if p := net.ParseIP(binding.HostIP); p != nil && !p.IsUnspecified() {
			// TODO(thaJeztah): use context-logger, so that this output can be suppressed (in tests).
			logrus.Warnf("ignoring IP-address (%s:%s) service will listen on '0.0.0.0'", net.JoinHostPort(binding.HostIP, binding.HostPort), portProto.String())
		}

		pr, err := network.ParsePortRange(binding.HostPort)
		if err != nil && binding.HostPort != "" {
			return nil, fmt.Errorf("invalid hostport binding (%s) for port (%d)", binding.HostPort, portProto.Num())
		}

		for p := range pr.All() {
			ports = append(ports, swarm.PortConfig{
				// TODO Name: ?
				Protocol:      portProto.Proto(),
				TargetPort:    uint32(portProto.Num()),
				PublishedPort: uint32(p.Num()),
				PublishMode:   swarm.PortConfigPublishModeIngress,
			})
		}
	}
	return ports, nil
}

View on GitHub (pinned to e9452d6e78)

When it happens

Trigger: Thrown at opts/swarmopts/port.go:172 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/c587496137e2c9cc.json. Report an issue: GitHub.