docker/cli · error

sysctl ' ' is not allowed

Error message

sysctl '%s' is not allowed

What it means

Thrown by ValidateSysctl (opts.go:269) when the input has no '=' separator or the key portion is empty. Docker restricts container sysctls to a known-safe allowlist and prefixes; before that check even runs, the value must be in `key=value` form. Without a key there is nothing to allow, so it is reported as 'not allowed'.

Solutions

1. Always pass sysctls as `name=value`, e.g. `--sysctl net.ipv4.ip_forward=1`.
2. Confirm the string contains exactly one '=' with a non-empty left side before submitting.
3. When generating sysctl flags from a map, format each entry as `k + "=" + fmt.Sprint(v)`.
4. Check for accidental trailing '=' with an empty value (key is fine but verify intent).

Example fix

// before
--sysctl net.ipv4.ip_forward
// after
--sysctl net.ipv4.ip_forward=1

// Ensure sysctl is key=value with non-empty key before validation.
if k, _, ok := strings.Cut(sysctl, "="); !ok || k == "" {
    return fmt.Errorf("sysctl %q must be name=value", sysctl)
}

When it happens

Trigger: Calling ValidateSysctl with a bare name like `net.ipv4.ip_forward` (no '=value'), an empty string, or `=value` (empty key). strings.Cut at line 267 returns ok=false or k="", triggering line 269.

Common situations: Passing just the sysctl name without its value (`--sysctl net.ipv4.ip_forward` instead of `--sysctl net.ipv4.ip_forward=1`), dropping the '=' during templating, or passing a value-only string.

Related errors

• is not a valid domain
• invalid label ' ': empty name
• label ' ' contains whitespaces
• failed to parse as a rational number
• invalid size

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

Appendix: source

Thrown at opts/opts.go:269

// ValidateSysctl validates a sysctl and returns it.
func ValidateSysctl(val string) (string, error) {
	validSysctlMap := map[string]bool{
		"kernel.msgmax":          true,
		"kernel.msgmnb":          true,
		"kernel.msgmni":          true,
		"kernel.sem":             true,
		"kernel.shmall":          true,
		"kernel.shmmax":          true,
		"kernel.shmmni":          true,
		"kernel.shm_rmid_forced": true,
	}
	validSysctlPrefixes := []string{
		"net.",
		"fs.mqueue.",
	}
	k, _, ok := strings.Cut(val, "=")
	if !ok || k == "" {
		return "", fmt.Errorf("sysctl '%s' is not allowed", val)
	}
	if validSysctlMap[k] {
		return val, nil
	}
	for _, vp := range validSysctlPrefixes {
		if strings.HasPrefix(k, vp) {
			return val, nil
		}
	}
	return "", fmt.Errorf("sysctl '%s' is not allowed", val)
}

// FilterOpt is a flag type for validating filters
type FilterOpt struct {
	filter client.Filters
}

// NewFilterOpt returns a new FilterOpt

View on GitHub (pinned to 4f84911bfe)