invalid publish opts format

Error message

invalid publish opts format (should be name=value but got '%s')

What it means

Returned in opts.go:908 by convertToStandardNotation when a --publish token using the name=value notation contains a param segment that is empty or has no `=`. The converter expects each comma-separated segment to be key=value (e.g. published=8080,target=80,protocol=tcp).

Solutions

Use the name=value form for every comma-separated segment: published=PORT,target=PORT,protocol=tcp.
Or use the classic short form ip:hostPort:containerPort[/proto].
Ensure no segment is empty and every segment has key and value.

Example fix

# before
docker run -p published=8080,,target=80 alpine

# after
docker run -p published=8080,target=80 alpine

Defensive patterns

Strategy: validation

Validate before calling

func validatePublish(tok string) error {
    if !strings.Contains(tok, "=") { return nil } // classic form
    for _, seg := range strings.Split(tok, ",") {
        k, v, ok := strings.Cut(seg, "=")
        if !ok || k == "" { return fmt.Errorf("bad publish segment %q", seg) }
        _ = v
    }
    return nil
}

Try / catch

// Deterministic format error; rebuild the token, do not retry.
if err := validatePublish(tok); err != nil { /* fix or use classic form */ }

Prevention

Use name=value for every comma-separated segment. Prefer the classic ip:hostPort:containerPort form when unsure. Avoid empty segments from trailing/double commas.

When it happens

Trigger: `docker run -p`/`--publish` with the structured notation where a segment is malformed: `--publish =80`, `--publish published=8080,=tcp`, or a segment with no `=` at all.

Common situations: Misunderstanding the structured publish syntax, a stray comma, a typo dropping the key, or a script that builds the token with an empty key.

Related errors

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/7f202d00eba3b3cb. Report an issue: GitHub.

Appendix: source

Thrown at cli/command/container/opts.go:908

	if ep.MacAddress != "" {
		ma, err := net.ParseMAC(strings.TrimSpace(ep.MacAddress))
		if err != nil {
			return nil, fmt.Errorf("%s is not a valid mac address", ep.MacAddress)
		}
		epConfig.MacAddress = network.HardwareAddr(ma)
	}
	return epConfig, nil
}

func convertToStandardNotation(ports []string) ([]string, error) {
	optsList := []string{}
	for _, publish := range ports {
		if strings.Contains(publish, "=") {
			params := map[string]string{"protocol": "tcp"}
			for param := range strings.SplitSeq(publish, ",") {
				k, v, ok := strings.Cut(param, "=")
				if !ok || k == "" {
					return optsList, fmt.Errorf("invalid publish opts format (should be name=value but got '%s')", param)
				}
				params[k] = v
			}
			optsList = append(optsList, fmt.Sprintf("%s:%s/%s", params["published"], params["target"], params["protocol"]))
		} else {
			optsList = append(optsList, publish)
		}
	}
	return optsList, nil
}

func parseLoggingOpts(loggingDriver string, loggingOpts []string) (map[string]string, error) {
	loggingOptsMap := opts.ConvertKVStringsToMap(loggingOpts)
	if loggingDriver == "none" && len(loggingOpts) > 0 {
		return map[string]string{}, fmt.Errorf("invalid logging opts for driver %s", loggingDriver)
	}
	return loggingOptsMap, nil
}

View on GitHub (pinned to 4f84911bfe)