What causes "invalid field %s" in docker/cli?

Ensure every field is key=value, e.g. name=mynet,alias=web.

invalid field

Error message

invalid field %s

What it means

Returned by NetworkOpt.Set (opts/network.go:62) when a long-syntax `--network` CSV field cannot be split into key=value. The parser only enters long-syntax mode when the regex detects at least one `word=word` segment; each field is then split on '=' and lowercased. This fires when a field lacks '=' or has an empty key after lowercasing (before trim).

Solutions

Ensure every field is key=value, e.g. name=mynet,alias=web.
Remove trailing/empty comma segments that produce empty fields.
If you only want the short form (network name), avoid including any key=value so the regex routes to the short-syntax branch.

Example fix

// before
--network "name=mynet,badfield,alias=web"

// after
--network "name=mynet,alias=web"

Defensive patterns

Strategy: validation

Validate before calling

func validateNetworkLongSyntax(val string) error {
    if !regexp.MustCompile(`\w+=\w+(,\w+=\w+)*`).MatchString(val) {
        return nil // short syntax, not checked here
    }
    r := csv.NewReader(strings.NewReader(val))
    fields, err := r.Read()
    if err != nil {
        return err
    }
    for _, f := range fields {
        k, _, ok := strings.Cut(strings.ToLower(f), "=")
        if !ok || k == "" {
            return fmt.Errorf("invalid field %q (expected key=value)", f)
        }
    }
    return nil
}

Try / catch

var n opts.NetworkOpt
if err := n.Set(spec); err != nil {
    return fmt.Errorf("network %q: %w", spec, err)
}

Prevention

Use either fully short (name only) or fully long (key=value) syntax; don't mix.
Strip trailing commas that create empty fields.
Build network specs from a typed struct.

When it happens

Trigger: A `--network` value like `name=mynet,badfield` (the regex matched because another field had =, but this field is bare), `=value` (empty key), or `,=,` style junk. Long syntax is triggered by the presence of any word=word pattern.

Common situations: Mixing long and short syntax fragments, trailing comma producing an empty field, or a stray value without a key.

Related errors

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

Appendix: source

Thrown at opts/network.go:62

	longSyntax, err := regexp.MatchString(`\w+=\w+(,\w+=\w+)*`, value)
	if err != nil {
		return err
	}

	var netOpt NetworkAttachmentOpts
	if longSyntax {
		csvReader := csv.NewReader(strings.NewReader(value))
		fields, err := csvReader.Read()
		if err != nil {
			return err
		}

		netOpt.Aliases = []string{}
		for _, field := range fields {
			// TODO(thaJeztah): these options should not be case-insensitive.
			key, val, ok := strings.Cut(strings.ToLower(field), "=")
			if !ok || key == "" {
				return fmt.Errorf("invalid field %s", field)
			}

			key = strings.TrimSpace(key)
			val = strings.TrimSpace(val)

			switch key {
			case networkOptName:
				netOpt.Target = val
			case networkOptAlias:
				netOpt.Aliases = append(netOpt.Aliases, val)
			case networkOptIPv4Address:
				netOpt.IPv4Address, err = netip.ParseAddr(val)
				if err != nil {
					return err
				}
			case networkOptIPv6Address:
				netOpt.IPv6Address, err = netip.ParseAddr(val)
				if err != nil {

View on GitHub (pinned to 4f84911bfe)