cannot apply allowed_modes configuration, %q is not a valid

Error message

cannot apply allowed_modes configuration, %q is not a valid userns_mode

What it means

During allowed_modes validation, each userns_mode allowlist entry is checked with containerapi.UsernsMode(v).Valid(). Only "" and "host" are valid userns modes, so any other string fails plugin setup with this error.

Source

Thrown at drivers/docker/config.go:898

	if len(allowedNS.PID) > 0 {
		for _, v := range allowedNS.PID {
			if !containerapi.PidMode(v).Valid() {
				return fmt.Errorf("cannot apply allowed_modes configuration, %q is not a valid pid_mode", v)
			}
		}
	}
	if len(allowedNS.IPC) > 0 {
		for _, v := range allowedNS.IPC {
			if !containerapi.IpcMode(v).Valid() {
				return fmt.Errorf("cannot apply allowed_modes configuration, %q is not a valid ipc_mode", v)
			}
		}
	}

	if len(allowedNS.Userns) > 0 {
		for _, v := range allowedNS.Userns {
			if !containerapi.UsernsMode(v).Valid() {
				return fmt.Errorf("cannot apply allowed_modes configuration, %q is not a valid userns_mode", v)
			}
		}
	}

	if len(allowedNS.UTS) > 0 {
		for _, v := range allowedNS.UTS {
			if !containerapi.UTSMode(v).Valid() {
				return fmt.Errorf("cannot apply allowed_modes configuration, %q is not a valid utc_mode", v)
			}
		}
	}
	return nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

Restrict userns_modes entries to "host" (or empty string).
Remove podman-style values like 'keep-id'/'auto' — they are not valid Docker userns_mode values.
If per-user remap is needed, configure daemon-level userns-remap instead of the task driver allowlist.
Re-run agent config validation after fixing.

Example fix

// before
userns_modes = ["keep-id"]
// after
userns_modes = ["host"]

Defensive patterns

Strategy: validation

Validate before calling

func validUserns(v string) bool { return v == "" || v == "host" }
for _, m := range cfg.AllowedModes.Userns {
    if !validUserns(m) { return fmt.Errorf("invalid userns_mode %q", m) }
}

Try / catch

Catch and reject the config at deploy time; the fix is always limiting entries to "" or "host".

Prevention

userns_mode only supports "" and "host" in Docker — nothing else.
Use daemon-level userns-remap for user namespace needs instead of allowlists.
Document the restriction in your platform's driver config guide.

When it happens

Trigger: Setting userns_modes = ["host", "something-else"] in the docker plugin allowlist, where the second value is not "" or "host".

Common situations: Operators assume arbitrary user-namespace strings are allowed (e.g. 'keep-id' from podman, 'auto'), but Docker's userns_mode only accepts host or empty.

Related errors

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/c6b0a5d5ec9242ef. Report an issue: GitHub.