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() checks the task-level pid_mode (ModePID). Unlike the plugin-level config, empty string is allowed (falls back to the driver default), but any non-empty value other than "private" or "host" is rejected when the task is validated.

Source

Thrown at drivers/java/driver.go:202

	// 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 for the task
	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 remove the field to use the driver default.
2. Trim whitespace and check casing in the job file (HCL).
3. Validate the job with `nomad job validate` before submitting.

Example fix

// before
task "app" {
  driver = "java"
  config {
    pid_mode = "container"
  }
}
// after
task "app" {
  driver = "java"
  config {
    pid_mode = "private"
  }
}

mode := taskCfg["pid_mode"]
if mode != "" && mode != "private" && mode != "host" {
    return fmt.Errorf("pid_mode must be '' (default), 'private' or 'host', got %q", mode)
}

if err := driver.StartTask(cfg); err != nil && strings.Contains(err.Error(), "pid_mode") {
    return fmt.Errorf("fix pid_mode in task config: %w", err)
}

When it happens

Trigger: A java task's config sets pid_mode to a value other than "", "private", or "host".

Common situations: Job spec typos ("isolated", "container"); case mismatches; copying docker driver's pid_mode values that don't apply; whitespace in the value.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• ipc_mode must be %q or %q, got %q
• default_pid_mode must be %q or %q, got %q
• default_ipc_mode must be %q or %q, got %q
• allow_caps configured with capabilities not supported by sys
• failed to decode driver config: %v

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