hashicorp/nomad · error

pid_mode must be %q or %q, got %q

Error message

pid_mode must be %q or %q, got %q

What it means

TaskConfig.validate() rejects a task whose ModePID (pid_mode) is not "", "private", or "host". Empty is allowed to inherit the driver default; anything else cannot be mapped to an executor isolation mode, so the task is rejected at registration/validation time.

Source

Thrown at drivers/exec/driver.go:223

	// ModeIPC indicates whether IPC namespace isolation is enabled for the task.
	// Must be "private" or "host" if set.
	ModeIPC string `codec:"ipc_mode"`

	// CapAdd is a set of linux capabilities to enable.
	CapAdd []string `codec:"cap_add"`

	// CapDrop is a set of linux capabilities to disable.
	CapDrop []string `codec:"cap_drop"`

	// WorkDir is the working directory inside the chroot
	WorkDir string `codec:"work_dir"`
}

func (tc *TaskConfig) validate() error {
	switch tc.ModePID {
	case "", executor.IsolationModePrivate, executor.IsolationModeHost:
	default:
		return fmt.Errorf("pid_mode must be %q or %q, got %q", executor.IsolationModePrivate, executor.IsolationModeHost, tc.ModePID)
	}

	switch tc.ModeIPC {
	case "", executor.IsolationModePrivate, executor.IsolationModeHost:
	default:
		return fmt.Errorf("ipc_mode must be %q or %q, got %q", executor.IsolationModePrivate, executor.IsolationModeHost, tc.ModeIPC)
	}

	supported := capabilities.Supported()
	badAdds := supported.Difference(capabilities.New(tc.CapAdd))
	if !badAdds.Empty() {
		return fmt.Errorf("cap_add configured with capabilities not supported by system: %s", badAdds)
	}

	badDrops := supported.Difference(capabilities.New(tc.CapDrop))
	if !badDrops.Empty() {
		return fmt.Errorf("cap_drop configured with capabilities not supported by system: %s", badDrops)
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set pid_mode to "private" or "host", or omit it to inherit the driver default
2. Remove Docker-only values like container:<id>
3. Fix value casing to lowercase

Example fix

// before
task "app" {
  driver = "exec"
  config {
    pid_mode = "none"
  }
}
// after
task "app" {
  driver = "exec"
  config {
    pid_mode = "private"
  }

if !(tc.ModePID == "" || tc.ModePID == "private" || tc.ModePID == "host") {
  return fmt.Errorf("invalid pid_mode %q", tc.ModePID)
}

func validPidMode(v string) bool {
  return v == "" || v == "private" || v == "host"
}

if err := task.Validate(); err != nil {
  if strings.Contains(err.Error(), "pid_mode") {
    cfg.ModePID = ""
  }
  return err
}

When it happens

Trigger: Submitting a job whose task config sets pid_mode to a value other than "private", "host", or "" (e.g. Docker-style "container:<id>", wrong casing, typo).

Common situations: Porting Docker task definitions to exec driver; using "none" for pid_mode; typos in job HCL; copy-paste between docker and exec driver task blocks.

Related errors

• ipc_mode must be %q or %q, got %q
• work_dir must be absolute but got relative path %q
• default_pid_mode must be %q or %q, got %q
• default_ipc_mode must be %q or %q, got %q
• cap_add configured with capabilities not supported by system

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