How to fix Error response from daemon: CPU period must be between 1000 and 1000000 in Docker

DockerINTERMEDIATELOWUpdated Dec 6, 2025· 195 views

This error occurs when you specify an invalid value for the --cpu-period flag in Docker. The CPU period must be between 1000 microseconds (1ms) and 1000000 microseconds (1 second). Fix it by using a valid period value, typically 100000 (100ms, the default).

Quick fix

Fixes Error response from daemon: CPU period must be between 1000 and 1000000

# Check if you're using --cpu-period in your command
docker run --cpu-period=500 myimage  # Error: too low (500 < 1000)
docker run --cpu-period=2000000 myimage  # Error: too high (2000000 > 1000000)
  1. Verify the current CPU period value
  2. Use a valid CPU period value
  3. Use --cpus instead of --cpu-period and --cpu-quota
  4. Fix Docker Compose CPU configuration
docker — error
# Check if you're using --cpu-period in your command
docker run --cpu-period=500 myimage  # Error: too low (500 < 1000)
docker run --cpu-period=2000000 myimage  # Error: too high (2000000 > 1000000)
Error response from daemon: CPU period must be between 1000 and 1000000

What this error means

The "CPU period must be between 1000 and 1000000" error indicates that you've specified an invalid value for Docker's `--cpu-period` flag. This flag works with the Linux CFS (Completely Fair Scheduler) to control how CPU time is allocated to containers. The CPU period defines the length of a scheduling period in microseconds. Docker enforces that this value must be between 1000 (1 millisecond) and 1000000 (1 second). The default period is 100000 microseconds (100ms), which works well for most use cases. The `--cpu-period` flag is typically used together with `--cpu-quota` to limit CPU usage. For example, with a period of 100000 and a quota of 50000, the container can use 50% of one CPU core. However, for most scenarios, the simpler `--cpus` flag is preferred as it handles these calculations automatically.

Typical symptoms

  • Docker run command fails with 'CPU period must be between 1000 and 1000000'
  • Docker Compose service fails to start with CPU period validation error
  • docker update command fails when modifying CPU period
  • Container creation fails in CI/CD pipeline due to invalid CPU configuration
  • Kubernetes pod fails to schedule with invalid resource constraints

Common causes

  1. CPU period value set below 1000 microseconds (less than 1ms)
  2. CPU period value set above 1000000 microseconds (more than 1 second)
  3. Typo in the --cpu-period value (missing or extra zeros)
  4. Confusing milliseconds with microseconds when setting the value
  5. Copy-pasting configuration from incompatible sources
  6. Using real-time scheduler period values for standard CFS scheduler

How to fix "Error response from daemon: CPU period must be between 1000 and 1000000"

1Verify the current CPU period value

First, check what CPU period value you're trying to set. The error occurs when the value is outside the valid range of 1000-1000000 microseconds.

bash
# Check if you're using --cpu-period in your command
docker run --cpu-period=500 myimage  # Error: too low (500 < 1000)
docker run --cpu-period=2000000 myimage  # Error: too high (2000000 > 1000000)

For existing containers, inspect the current CPU period:

bash
docker inspect --format='{{.HostConfig.CpuPeriod}}' <container_name>

The default value is 100000 (100ms). A value of 0 means no limit is set.

2Use a valid CPU period value

Set the CPU period to a value between 1000 and 1000000 microseconds:

bash
# Default and recommended value (100ms)
docker run --cpu-period=100000 --cpu-quota=50000 myimage

# Shorter period for more responsive throttling (10ms)
docker run --cpu-period=10000 --cpu-quota=5000 myimage

# Longer period for less overhead (500ms)
docker run --cpu-period=500000 --cpu-quota=250000 myimage

Valid range reference:
| Value | Meaning |
|-------|---------|
| 1000 | 1 millisecond (minimum) |
| 10000 | 10 milliseconds |
| 100000 | 100 milliseconds (default) |
| 500000 | 500 milliseconds |
| 1000000 | 1 second (maximum) |

3Use --cpus instead of --cpu-period and --cpu-quota

For most use cases, the --cpus flag is simpler and less error-prone:

bash
# Limit container to 0.5 CPU cores
docker run --cpus=0.5 myimage

# Limit container to 2 CPU cores
docker run --cpus=2 myimage

# Limit container to 1.5 CPU cores
docker run --cpus=1.5 myimage

The --cpus flag internally converts to --cpu-period and --cpu-quota:
- --cpus=0.5 is equivalent to --cpu-period=100000 --cpu-quota=50000
- --cpus=1.5 is equivalent to --cpu-period=100000 --cpu-quota=150000

This approach avoids period validation errors and is easier to understand.

4Fix Docker Compose CPU configuration

In Docker Compose, use the cpus key under deploy.resources for simplicity:

yaml
version: '3.8'
services:
  myservice:
    image: myimage
    deploy:
      resources:
        limits:
          cpus: '0.5'
        reservations:
          cpus: '0.25'

If you need to use cpu_period explicitly (legacy Compose format):

yaml
version: '2.4'
services:
  myservice:
    image: myimage
    cpu_period: 100000
    cpu_quota: 50000

Note: The cpu_period and cpu_quota keys are only available in Compose file version 2.x. For version 3.x, use deploy.resources.limits.cpus instead.

5Update running container CPU settings

If you need to modify CPU settings on a running container, use docker update:

bash
# Update using --cpus (recommended)
docker update --cpus=0.5 <container_name>

# Update using --cpu-period and --cpu-quota
docker update --cpu-period=100000 --cpu-quota=50000 <container_name>

Verify the update was applied:

bash
docker inspect --format='CpuPeriod: {{.HostConfig.CpuPeriod}}, CpuQuota: {{.HostConfig.CpuQuota}}' <container_name>

Note: Changes take effect immediately without restarting the container.

6Understand the relationship between period and quota

The CPU period and quota work together to limit CPU usage:

bash
CPU Usage = cpu_quota / cpu_period

Examples:
| Period | Quota | CPU Usage |
|--------|-------|-----------|
| 100000 | 50000 | 50% of 1 CPU |
| 100000 | 100000 | 100% of 1 CPU |
| 100000 | 200000 | 200% (2 CPUs) |
| 50000 | 25000 | 50% of 1 CPU |

Choosing period values:
- Shorter periods (10000-50000): More responsive throttling, higher scheduling overhead
- Default period (100000): Good balance for most workloads
- Longer periods (200000-1000000): Lower overhead, but bursty behavior

For most applications, stick with the default period of 100000 and adjust only the quota (or use --cpus).

Advanced notes

CFS Scheduler Background: Docker uses the Linux Completely Fair Scheduler (CFS) bandwidth control to limit CPU usage. The --cpu-period and --cpu-quota flags map directly to the cgroup parameters cpu.cfs_period_us and cpu.cfs_quota_us.

You can verify these settings in the cgroup filesystem:

bash
# For cgroup v1
cat /sys/fs/cgroup/cpu/docker/<container_id>/cpu.cfs_period_us
cat /sys/fs/cgroup/cpu/docker/<container_id>/cpu.cfs_quota_us

# For cgroup v2
cat /sys/fs/cgroup/docker/<container_id>/cpu.max

Real-time Scheduler Note: Don't confuse --cpu-period (CFS scheduler) with --cpu-rt-period (real-time scheduler). The real-time scheduler has different constraints:
- --cpu-rt-period: Default 1000000 (1 second), range varies by kernel
- --cpu-rt-runtime: Time reserved for real-time tasks per period

Kubernetes CPU Limits: In Kubernetes, CPU limits are specified differently. A limit of "500m" (500 millicores) translates to --cpu-quota=50000 with the default period. Kubernetes handles the conversion automatically.

Performance Considerations:
- Very short periods (near 1000) can cause high scheduling overhead
- Very long periods (near 1000000) can cause noticeable latency spikes when throttling kicks in
- The default 100000 (100ms) provides a good balance

Docker Desktop Behavior: On Docker Desktop (Mac/Windows), CPU limits work differently because containers run in a Linux VM. The actual behavior depends on the hypervisor and available host resources.

Frequently asked questions

What does "Error response from daemon: CPU period must be between 1000 and 100000" mean?
The "CPU period must be between 1000 and 1000000" error indicates that you've specified an invalid value for Docker's --cpu-period flag. This flag works with the Linux CFS (Completely Fair Scheduler) to control how CPU time is allocated to containers. The CPU period defines the length of a scheduling period in microseconds.
How do I fix "Error response from daemon: CPU period must be between 1000 and 100000"?
This error occurs when you specify an invalid value for the --cpu-period flag in Docker. The CPU period must be between 1000 microseconds (1ms) and 1000000 microseconds (1 second). Fix it by using a valid period value, typically 100000 (100ms, the default).
What causes "Error response from daemon: CPU period must be between 1000 and 100000"?
CPU period value set below 1000 microseconds (less than 1ms) CPU period value set above 1000000 microseconds (more than 1 second) Typo in the --cpu-period value (missing or extra zeros)
Is the "Error response from daemon: CPU period must be between 1000 and 100000" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading