invalid value: . Valid memory swappiness range is 0-100

Error message

invalid value: %d. Valid memory swappiness range is 0-100

What it means

Returned in opts.go:368 when --memory-swappiness is set to a value outside the documented kernel range. The sentinel -1 (meaning inherit) is allowed; any other value below 0 or above 100 is rejected.

Solutions

Use a value between 0 and 100 inclusive.
Use -1 only to inherit the host setting.
If unsure, omit the flag to use the daemon default.

Example fix

# before
docker run --memory-swappiness 150 alpine

# after
docker run --memory-swappiness 60 alpine

Defensive patterns

Strategy: validation

Validate before calling

func validSwappiness(v int) bool { return v == -1 || (v >= 0 && v <= 100) }
if !validSwappiness(swappiness) {
    return fmt.Errorf("memory swappiness %d out of range [0,100] or -1", swappiness)
}

Type guard

func isValidSwappiness(v int) bool {
    return v == -1 || (v >= 0 && v <= 100)
}

Try / catch

// Range check is deterministic; correct the value, no retry.
if !isValidSwappiness(v) { v = defaultSwappiness }

Prevention

Remember the scale is 0-100 (not the kernel 0-255). Use -1 to inherit, omit otherwise.
Validate in wrappers before invoking docker.

When it happens

Trigger: `docker run --memory-swappiness N` with N not in [0,100] and not -1 (e.g. 150, -2).

Common situations: Confusing swappiness scale with a 0-255 kernel scale, copy-pasting a value from a different tool, or a negative value other than -1.

Related errors

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

Appendix: source

Thrown at cli/command/container/opts.go:368

	if copts.macAddress != "" {
		if _, err := net.ParseMAC(strings.TrimSpace(copts.macAddress)); err != nil {
			return nil, fmt.Errorf("%s is not a valid mac address", copts.macAddress)
		}
	}
	if copts.stdin {
		attachStdin = true
	}
	// If -a is not set, attach to stdout and stderr
	if copts.attach.Len() == 0 {
		attachStdout = true
		attachStderr = true
	}

	var err error

	swappiness := copts.swappiness
	if swappiness != -1 && (swappiness < 0 || swappiness > 100) {
		return nil, fmt.Errorf("invalid value: %d. Valid memory swappiness range is 0-100", swappiness)
	}

	var binds []string
	volumes := copts.volumes.GetMap()
	// add any bind targets to the list of container volumes
	for bind := range volumes {
		parsed, err := volumespec.Parse(bind)
		if err != nil {
			return nil, err
		}

		if parsed.Source != "" {
			toBind := bind

			if parsed.Type == string(mount.TypeBind) {
				if hostPart, targetPath, ok := strings.Cut(bind, ":"); ok {
					if !filepath.IsAbs(hostPart) && strings.HasPrefix(hostPart, ".") {
						if absHostPart, err := filepath.Abs(hostPart); err == nil {

View on GitHub (pinned to 4f84911bfe)