docker/cli · error

invalid key/value pair format in driver options

Error message

invalid key/value pair format in driver options

What it means

docker network connect accepts driver-specific options via --driver-opt key=value. convertDriverOpt (cli/command/network/connect.go:88-96) splits each option on the first '=' with strings.Cut; if there is no '=' at all, or the key is empty/whitespace-only after trimming, the pair is malformed and the CLI rejects it before calling the NetworkConnect API. An empty value ('key=') is allowed; a missing or blank key is not.

Source

Thrown at cli/command/network/connect.go:95

				LinkLocalIPs: toNetipAddrSlice(options.linklocalips),
			},
			Links:      options.links.GetSlice(),
			Aliases:    options.aliases,
			DriverOpts: driverOpts,
			GwPriority: options.gwPriority,
		},
	})
	return err
}

func convertDriverOpt(options []string) (map[string]string, error) {
	driverOpt := make(map[string]string)
	for _, opt := range options {
		k, v, ok := strings.Cut(opt, "=")
		// TODO(thaJeztah): we should probably not accept whitespace here (both for key and value).
		k = strings.TrimSpace(k)
		if !ok || k == "" {
			return nil, errors.New("invalid key/value pair format in driver options")
		}
		driverOpt[k] = strings.TrimSpace(v)
	}
	return driverOpt, nil
}

func toNetipAddrSlice(ips []net.IP) []netip.Addr {
	if len(ips) == 0 {
		return nil
	}
	netIPs := make([]netip.Addr, 0, len(ips))
	for _, ip := range ips {
		netIPs = append(netIPs, toNetipAddr(ip))
	}
	return netIPs
}

func toNetipAddr(ip net.IP) netip.Addr {

View on GitHub (pinned to e9452d6e78)

Solutions

1. Write each option as key=value: docker network connect --driver-opt com.docker.network.endpoint.ifname=eth2 mynet myctr
2. Repeat the flag for multiple options rather than concatenating them: --driver-opt k1=v1 --driver-opt k2=v2
3. In scripts, validate that the key variable is non-empty before composing "$KEY=$VALUE"

Example fix

# before
docker network connect --driver-opt ifname mynet myctr
# after
docker network connect --driver-opt com.docker.network.endpoint.ifname=eth2 mynet myctr

When it happens

Trigger: `docker network connect --driver-opt somekey mynet ctr` (no '='), `--driver-opt "=value"` or `--driver-opt " =value"` (empty/whitespace key). Any element of the --driver-opt list failing the k,v,ok := strings.Cut(opt, "="); ok && k != "" check.

Common situations: Typos omitting the '=' (writing --driver-opt macvlan_mode bridge instead of macvlan_mode=bridge); shell quoting/variable expansion producing an empty key (--driver-opt "$KEY=$VAL" with unset KEY); passing comma-joined or space-separated options as one malformed argument.

Related errors

• no name set for network
• plugin candidate path cannot be empty
• plugin SchemaVersion version cannot be empty
• config file is required
• source can not be empty

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