hashicorp/nomad · error

ipc_mode must be %q or %q, got %q

Error message

ipc_mode must be %q or %q, got %q

What it means

TaskConfig.validate guard in the java driver: ModeIPC was set to a value other than the allowed executor.IsolationModePrivate or executor.IsolationModeHost (or empty); the task config is rejected at registration.

Source

Thrown at drivers/java/driver.go:209

	// 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)
	}

	if tc.WorkDir != "" && !filepath.IsAbs(tc.WorkDir) {
		return fmt.Errorf("work_dir must be an absolute path: %s", tc.WorkDir)
	}
	return nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set ipc_mode to "private" or "host", or remove it to inherit the driver default.
2. Run `nomad job validate` to catch the mistake before submission.
3. Check that the value targets IPC mode, not PID mode or capabilities.

Example fix

// before
config {
  ipc_mode = "shared"
}
// after
config {
  ipc_mode = "host"
}

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

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

When it happens

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

Common situations: Typos in job specs ("share", "none"); mixing up pid_mode/ipc_mode values; older jobs written for drivers with different allowed values.

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

• pid_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/c388bc3e113dd2ab. Report an issue: GitHub.