invalid key value pair format in driver options

Error message

invalid key value pair format in driver options

What it means

Returned by parseDriverOpt (opts/network.go:153) when a 'driver-opt' value in the --network long syntax does not contain an '=' separator or has an empty key after lowercasing. Driver options must be specified as 'driver-opt=key=value' where the inner key=value is the driver-specific option.

Solutions

Format driver-opt as 'driver-opt=key=value', e.g., 'driver-opt=com.docker.network.bridge.enable_icc=true'.
Ensure the inner key (before the inner '=') is non-empty.

Example fix

// before: missing value in driver-opt
// docker run --network name=mynet,driver-opt=com.docker.network.bridge.enable_icc nginx

// after: include key=value
// docker run --network name=mynet,driver-opt=com.docker.network.bridge.enable_icc=true nginx

Defensive patterns

Strategy: validation

Validate before calling

func validateDriverOpt(spec string) error {
    for _, field := range strings.Split(spec, ",") {
        key, val, ok := strings.Cut(strings.ToLower(field), "=")
        if ok && key == "driver-opt" {
            innerKey, _, innerOK := strings.Cut(val, "=")
            if !innerOK || innerKey == "" {
                return fmt.Errorf("driver-opt requires key=value format: %s", val)
            }
        }
    }
    return nil
}

Try / catch

if err := networkOpt.Set(value); err != nil {
    if err.Error() == "invalid key value pair format in driver options" {
        return fmt.Errorf("format driver-opt as 'driver-opt=key=value', e.g., driver-opt=com.docker.network.bridge.enable_icc=true")
    }
    return err
}

Prevention

Format driver-opt as 'driver-opt=key=value' with an inner '=' separator.
Ensure the inner key (before '=') is non-empty.
Validate driver-opt values before passing to NetworkOpt.Set.

When it happens

Trigger: A --network value contains 'driver-opt=<val>' where <val> lacks '=' (e.g., 'driver-opt=debug') or starts with '=' (e.g., 'driver-opt==value' producing empty key). parseDriverOpt uses strings.Cut on '=' and checks that both ok is true and key is non-empty.

Common situations: Missing the value part of a driver option (e.g., 'driver-opt=com.docker.network.bridge.enable_icc' without '=true'), typo omitting '=', or misunderstanding that driver-opt requires an inner key=value pair.

Related errors

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

Appendix: source

Thrown at opts/network.go:153

	return ""
}

// NetworkMode return the network mode for the network option
func (n *NetworkOpt) NetworkMode() string {
	networkIDOrName := "default"
	netOptVal := n.Value()
	if len(netOptVal) > 0 {
		networkIDOrName = netOptVal[0].Target
	}
	return networkIDOrName
}

func parseDriverOpt(driverOpt string) (string, string, error) {
	// TODO(thaJeztah): these options should not be case-insensitive.
	// TODO(thaJeztah): should value be converted to lowercase as well, or only the key?
	key, value, ok := strings.Cut(strings.ToLower(driverOpt), "=")
	if !ok || key == "" {
		return "", "", errors.New("invalid key value pair format in driver options")
	}
	key = strings.TrimSpace(key)
	value = strings.TrimSpace(value)
	return key, value, nil
}

View on GitHub (pinned to 4f84911bfe)