What causes "invalid gw-priority (%s): %w" in docker/cli?

Provide an integer: gw-priority=10.

invalid gw-priority ( )

Error message

invalid gw-priority (%s): %w

What it means

Returned by NetworkOpt.Set (opts/network.go:107) when the `gw-priority` field's value fails strconv.Atoi. The underlying error is unwrapped from *strconv.NumError and wrapped with the offending value, exposing the concrete parse failure (typically ErrSyntax for non-numeric input or ErrRange for out-of-int-range). gw-priority sets the gateway priority for the network attachment.

Solutions

Provide an integer: gw-priority=10.
Remove the field if you don't need to set gateway priority (it defaults to 0).
Avoid decimals and descriptive strings; priority is a plain integer ranking.

Example fix

// before
--network "name=mynet,gw-priority=high"

// after
--network "name=mynet,gw-priority=10"

Defensive patterns

Strategy: validation

Validate before calling

func validateGwPriority(v string) error {
    if _, err := strconv.Atoi(v); err != nil {
        return fmt.Errorf("gw-priority must be an integer, got %q", v)
    }
    return nil
}

Try / catch

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

Prevention

Treat gw-priority as a plain integer; reject decimals and words in your UI.
Omit the field when you don't need to rank gateways.
Document that higher = preferred.

When it happens

Trigger: Passing `gw-priority=high`, `gw-priority=1.5`, `gw-priority=` (empty — though that hits Atoi with empty string => ErrSyntax), or a value exceeding int range on the host.

Common situations: Using a descriptive word instead of an integer, decimal priority, or copy-paste from a doc that used a non-numeric placeholder.

Related errors

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

Appendix: source

Thrown at opts/network.go:107

				}
				netOpt.LinkLocalIPs = append(netOpt.LinkLocalIPs, a)
			case driverOpt:
				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"

View on GitHub (pinned to 4f84911bfe)