docker/cli · error

invalid field key {key}

Error message

invalid field key {key}

What it means

Returned by NetworkOpt.Set (opts/network.go:110) in the long-syntax --network parser when a key does not match any known network option. Recognized keys are: name, alias, ip, ip6, mac-address, link-local-ip, driver-opt, and gw-priority. Any other key falls through to the default case and triggers this error with the offending key appended.

Source

Thrown at opts/network.go:110

				key, val, err = parseDriverOpt(val)
				if err != nil {
					return err
				}
				if netOpt.DriverOpts == nil {
					netOpt.DriverOpts = make(map[string]string)
				}
				netOpt.DriverOpts[key] = val
			case gwPriorityOpt:
				netOpt.GwPriority, err = strconv.Atoi(val)
				if err != nil {
					var numErr *strconv.NumError
					if errors.As(err, &numErr) {
						err = numErr.Err
					}
					return fmt.Errorf("invalid gw-priority (%s): %w", val, err)
				}
			default:
				return errors.New("invalid field key " + key)
			}
		}
		if len(netOpt.Target) == 0 {
			return errors.New("network name/id is not specified")
		}
	} else {
		netOpt.Target = value
	}
	n.options = append(n.options, netOpt)
	return nil
}

// Type returns the type of this option
func (*NetworkOpt) Type() string {
	return "network"
}

// Value returns the networkopts

View on GitHub (pinned to 4f84911bfe)

Solutions

1. Check the key name against the allowed list: name, alias, ip, ip6, mac-address, link-local-ip, driver-opt, gw-priority.
2. Fix typos in the key name (e.g., 'aliases' → 'alias').
3. For multiple aliases, repeat the alias key: 'name=net,alias=a,alias=b'.

Example fix

// before: unknown key
// docker run --network name=mynet,aliases=web nginx

// after: correct key name
// docker run --network name=mynet,alias=web nginx

var validNetworkKeys = map[string]bool{
    "name": true, "alias": true, "ip": true, "ip6": true,
    "mac-address": true, "link-local-ip": true, "driver-opt": true,
    "gw-priority": true,
}

func validateNetworkKeys(spec string) error {
    for _, field := range strings.Split(spec, ",") {
        key, _, ok := strings.Cut(strings.ToLower(field), "=")
        if ok && key != "" && !validNetworkKeys[key] {
            return fmt.Errorf("unknown network key %q; valid: name, alias, ip, ip6, mac-address, link-local-ip, driver-opt, gw-priority", key)
        }
    }
    return nil
}

if err := networkOpt.Set(value); err != nil {
    if strings.Contains(err.Error(), "invalid field key") {
        return fmt.Errorf("unknown --network option; valid keys: name, alias, ip, ip6, mac-address, link-local-ip, driver-opt, gw-priority")
    }
    return err
}

When it happens

Trigger: A --network value in long syntax (key=value comma-separated) contains an unrecognized key. For example: '--network name=mynet,foo=bar' — 'foo' is not a valid network attachment option. Keys are lowercased before matching, so case differences don't cause this.

Common situations: Typo in an option name (e.g., 'aliases' instead of 'alias'), using an option that belongs to a different flag, or attempting to use an unsupported network configuration key.

Related errors

• network name/id is not specified
• invalid key value pair format in driver options
• conflicting options: cannot attach both user-defined and non
• conflicting options: cannot specify both --network-alias and
• conflicting options: cannot specify both --link and per-netw

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