hashicorp/nomad · error

invalid value for cpu_cfs_period

Error message

invalid value for cpu_cfs_period

What it means

Nomad's Docker driver validates the user-supplied cpu_cfs_period driver option when CPUHardLimit is enabled. The CFS period must be within 0..1000000 microseconds; a negative value or one above 1,000,000 is rejected before any Docker API call is made. Period 0 means 'use the scheduler-derived default' (task.Resources.LinuxResources.CPUPeriod).

Source

Thrown at drivers/docker/driver.go:1163

	// Setting cpuset_cpus in driver config is no longer supported (it has
	// not worked correctly since Nomad 0.12)
	if driverConfig.CPUSetCPUs != "" {
		d.logger.Warn("cpuset_cpus is no longer supported")
	}

	// Enable tini (docker-init) init system.
	if driverConfig.Init {
		hostConfig.Init = &driverConfig.Init
	}

	// Calculate CPU Quota
	// cfs_quota_us is the time per core, so we must
	// multiply the time by the number of cores available
	// See https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/resource_management_guide/sec-cpu
	if driverConfig.CPUHardLimit {
		numCores := runtime.NumCPU()
		if driverConfig.CPUCFSPeriod < 0 || driverConfig.CPUCFSPeriod > 1000000 {
			return c, fmt.Errorf("invalid value for cpu_cfs_period")
		}
		if driverConfig.CPUCFSPeriod == 0 {
			driverConfig.CPUCFSPeriod = task.Resources.LinuxResources.CPUPeriod
		}
		hostConfig.CPUPeriod = driverConfig.CPUCFSPeriod
		hostConfig.CPUQuota = int64(task.Resources.LinuxResources.PercentTicks*float64(driverConfig.CPUCFSPeriod)) * int64(numCores)
	}

	// Windows does not support MemorySwap/MemorySwappiness #2193
	if runtime.GOOS == "windows" {
		hostConfig.MemorySwap = 0
		hostConfig.MemorySwappiness = nil
	} else {
		hostConfig.MemorySwap = memory

		// disable swap explicitly in non-Windows environments
		if cgroupslib.MaybeDisableMemorySwappiness() != nil {
			hostConfig.MemorySwappiness = new(int64(*(cgroupslib.MaybeDisableMemorySwappiness())))

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set cpu_cfs_period to a value between 1 and 1000000 (microseconds), e.g. 100000
2. Remove the cpu_cfs_period option entirely so 0 falls back to the task's LinuxResources.CPUPeriod default
3. If you only wanted quota control, keep the default period and only adjust the CPU amount

Example fix

// before
driver {
  docker {}
  cpu_hard_limit = true
  cpu_cfs_period = 5000000
}
// after
driver {
  docker {}
  cpu_hard_limit = true
  cpu_cfs_period = 100000
}

if p := jobDriverCfg.CPUCFSPeriod; p < 0 || p > 1000000 {
  return fmt.Errorf("cpu_cfs_period must be 0..1000000, got %d", p)
}

func validCFSPeriod(p int64) bool { return p == 0 || (p > 0 && p <= 1000000) }

period, err := resolveCFSPeriod(cfg); if err != nil { return fmt.Errorf("invalid cpu_cfs_period: %w", err) }

When it happens

Trigger: Starting a task with a docker driver config where cpu_cfs_period is set to a negative number or a value greater than 1000000 while cpu_hard_limit is true, via createContainerConfig called from StartTask.

Common situations: Copy-pasting a Docker daemon --cpu-cfs-period style value in nanoseconds instead of microseconds; typos like 10000000 (extra zero); tuning attempts that exceed the kernel CFS period max.

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

• failed to parse security_opt configuration: %v
• failed to parse ulimit configuration: %v
• Port %q not found, check network block
• failed to parse ipv4_address %q: %v
• host path must be set in configuration for devices

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