hashicorp/nomad · error

pids_limit cannot be greater than nomad plugin config pids_l

Error message

pids_limit cannot be greater than nomad plugin config pids_limit: %d

What it means

The docker plugin supports an operator-level pids_limit cap. If a job's task config specifies a pids_limit larger than the plugin config's pids_limit (when that cap is > 0), container configuration fails. This keeps task PID usage within operator-enforced bounds.

Source

Thrown at drivers/docker/driver.go:1102

		if driverConfig.Isolation == "" {
			driverConfig.Isolation = windowsIsolationModeHyperV
		}
		if !slices.Contains(windowsIsolationModes, driverConfig.Isolation) {
			return c, fmt.Errorf("Unsupported isolation mode \"%s\"", driverConfig.Isolation)
		}
	}

	var pidsLimit int64 = -1 // default unlimited

	// Pids limit defined in Nomad plugin config.
	if d.config.PidsLimit > 0 {
		pidsLimit = d.config.PidsLimit
	}

	// Override Nomad plugin config pids limit, by user defined pids limit.
	if driverConfig.PidsLimit > 0 {
		if d.config.PidsLimit > 0 && driverConfig.PidsLimit > d.config.PidsLimit {
			return c, fmt.Errorf("pids_limit cannot be greater than nomad plugin config pids_limit: %d", d.config.PidsLimit)
		}
		pidsLimit = driverConfig.PidsLimit
	}

	cpuShares := d.cpuResources(task.Resources.LinuxResources.CPUShares)

	hostConfig := &containerapi.HostConfig{
		CgroupnsMode: containerapi.CgroupnsMode(driverConfig.CgroupnsMode),
		// do not set cgroup parent anymore

		OomScoreAdj: driverConfig.OOMScoreAdj, // ignored on platforms other than linux

		// Binds are used to mount a host volume into the container. We mount a
		// local directory for storage and a shared alloc directory that can be
		// used to share data between different tasks in the same task group.
		Binds: binds,

		Isolation:    containerapi.Isolation(driverConfig.Isolation),

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Lower the task's pids_limit in the job spec to be <= the plugin config pids_limit.
2. Raise the plugin config pids_limit in the Nomad client docker plugin block and reload the client.
3. Remove the plugin-level cap (pids_limit = 0) if per-job limits should be unrestricted.
4. Target the task at clients whose plugin cap accommodates the requested limit.

Example fix

// job task config
// before
pids_limit = 500  // plugin cap = 100
// after
pids_limit = 100

function validatePidsLimit(taskPidsLimit, pluginPidsLimit) {
  if (taskPidsLimit > 0 && pluginPidsLimit > 0 && taskPidsLimit > pluginPidsLimit) {
    throw new Error(`task pids_limit ${taskPidsLimit} exceeds plugin cap ${pluginPidsLimit}`);
  }
}

try {
  await client.jobs.submit(job);
} catch (err) {
  if (/pids_limit cannot be greater/.test(err.message)) {
    console.error('Lower task pids_limit or raise the plugin cap in client config');
  }
  throw err;
}

When it happens

Trigger: Task sets pids_limit = 500 while the client plugin config has pids_limit = 100; both values > 0 and task > plugin cap during createContainerConfig.

Common situations: Operators lowering the cluster-wide plugin pids_limit after jobs were authored with higher values; jobs copied from clusters without a plugin cap; forgetting to update job specs after tightening client policy.

Related errors

• failed to parse 'image_delay' duration: %v
• failed to parse 'period' duration: %v
• failed to parse 'creation_grace' duration: %v
• creation_grace is less than minimum, %v
• failed to parse 'pull_activity_timeout' duration: %v

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