How to fix Error response from daemon: invalid CPU shares in Docker

DockerINTERMEDIATELOWUpdated Dec 6, 2025· 142 views

This Docker error occurs when you specify an invalid value for the --cpu-shares flag. CPU shares must be an integer value of 2 or higher (or 0 to use the default of 1024). The fix involves using a valid integer within the acceptable range.

Quick fix

Fixes Error response from daemon: invalid CPU shares

# Valid values
docker run --cpu-shares 512 myimage    # Valid: integer >= 2
docker run --cpu-shares 1024 myimage   # Valid: default value
docker run --cpu-shares 2048 myimage   # Valid: higher than default
docker run -c 0 myimage                # Valid: 0 defaults to 1024

# Invalid values that cause the error
docker run --cpu-shares 1 myimage      # Invalid: must be >= 2
docker run --cpu-shares 0.5 myimage    # Invalid: float not allowed
docker run --cpu-shares "high" myimage # Invalid: must be numeric
  1. Verify the CPU shares value is a valid integer
  2. Fix CPU shares in docker run commands
  3. Fix cpu_shares in docker-compose.yml
  4. Update running containers with valid CPU shares
docker — error
# Valid values
docker run --cpu-shares 512 myimage    # Valid: integer >= 2
docker run --cpu-shares 1024 myimage   # Valid: default value
docker run --cpu-shares 2048 myimage   # Valid: higher than default
docker run -c 0 myimage                # Valid: 0 defaults to 1024
# Invalid values that cause the error
docker run --cpu-shares 1 myimage      # Invalid: must be >= 2
docker run --cpu-shares 0.5 myimage    # Invalid: float not allowed
docker run --cpu-shares "high" myimage # Invalid: must be numeric
Error response from daemon: invalid CPU shares

What this error means

The "invalid CPU shares" error indicates that Docker cannot accept the CPU share value you provided. CPU shares in Docker control how much CPU time a container gets relative to other containers when CPU resources are constrained. The --cpu-shares (or -c) flag sets a relative weight for CPU scheduling. Valid values are integers from 2 to 1024 (or higher), with 1024 being the default. A value of 0 is also accepted and defaults to 1024. Values of 1 or non-integer values (like floats or strings) are considered invalid. CPU shares only come into effect when multiple containers are competing for CPU resources. For example, if Container A has 1024 shares and Container B has 512 shares, Container A gets twice as much CPU time as Container B when both are CPU-bound. When there's no contention, containers can use all available CPU regardless of their share value.

Typical symptoms

  • Docker run or create command fails with 'invalid CPU shares' error
  • Docker Compose fails to start services with cpu_shares configuration
  • Container update command fails when changing CPU shares
  • Error message includes 'Error response from daemon: invalid CPU shares'
  • Build or deployment scripts fail at container creation step

Common causes

  1. Using a CPU shares value of 1 (minimum valid value is 2)
  2. Passing a float/decimal value instead of an integer (e.g., 0.5 or 512.5)
  3. Providing a string instead of an integer (common when reading from .env files)
  4. Negative CPU shares value
  5. Non-numeric characters in the cpu-shares value
  6. Empty or null value passed to --cpu-shares flag
  7. Type conversion issues in docker-compose when parsing .env variables

How to fix "Error response from daemon: invalid CPU shares"

1Verify the CPU shares value is a valid integer

Check that your CPU shares value is an integer of 2 or higher. The default value is 1024.

bash
# Valid values
docker run --cpu-shares 512 myimage    # Valid: integer >= 2
docker run --cpu-shares 1024 myimage   # Valid: default value
docker run --cpu-shares 2048 myimage   # Valid: higher than default
docker run -c 0 myimage                # Valid: 0 defaults to 1024

# Invalid values that cause the error
docker run --cpu-shares 1 myimage      # Invalid: must be >= 2
docker run --cpu-shares 0.5 myimage    # Invalid: float not allowed
docker run --cpu-shares "high" myimage # Invalid: must be numeric

To check your current command, review the exact value being passed to --cpu-shares or -c flag.

2Fix CPU shares in docker run commands

Update your docker run command to use a valid integer value:

bash
# Change from invalid value
docker run --cpu-shares 1 -d nginx

# To valid value (minimum is 2)
docker run --cpu-shares 2 -d nginx

# Or use a standard proportion value
docker run --cpu-shares 512 -d nginx   # Half of default
docker run --cpu-shares 1024 -d nginx  # Default (same as omitting)
docker run --cpu-shares 2048 -d nginx  # Double the default

Common CPU share values:
- 256: 1/4 of default priority
- 512: Half of default priority
- 1024: Default priority (same as not specifying)
- 2048: Double the default priority

3Fix cpu_shares in docker-compose.yml

When using Docker Compose, ensure cpu_shares is defined as an integer:

yaml
# docker-compose.yml
version: "3.9"
services:
  web:
    image: nginx
    cpu_shares: 512  # Valid: integer value

  worker:
    image: myworker
    cpu_shares: 1024  # Valid: default weight

Common mistake with .env files:

yaml
# This can cause issues if CPU_SHARES is read as a string
services:
  web:
    cpu_shares: ${CPU_SHARES}  # May be parsed as string

Fix by ensuring proper type conversion:

yaml
services:
  web:
    cpu_shares: ${CPU_SHARES:-1024}  # Default to 1024 if not set

Make sure your .env file has a plain integer:

bash
# .env
CPU_SHARES=512
4Update running containers with valid CPU shares

If you need to update the CPU shares of a running container:

bash
# Check current container settings
docker inspect --format '{{.HostConfig.CpuShares}}' container_name

# Update to a valid value
docker update --cpu-shares 512 container_name

# Verify the change
docker inspect --format '{{.HostConfig.CpuShares}}' container_name

Note: The docker update command requires the container to be using the appropriate cgroup driver. If you see errors, the container may need to be recreated with the new value.

5Handle environment variable type issues

When CPU shares values come from environment variables, ensure proper handling:

In shell scripts:

bash
#!/bin/bash
# Ensure the value is an integer
CPU_SHARES=${CPU_SHARES:-1024}

# Validate before using
if [[ ! "$CPU_SHARES" =~ ^[0-9]+$ ]] || [ "$CPU_SHARES" -eq 1 ]; then
    echo "Invalid CPU_SHARES value, using default 1024"
    CPU_SHARES=1024
fi

docker run --cpu-shares "$CPU_SHARES" -d myimage

In CI/CD pipelines:

yaml
# GitHub Actions example
- name: Run container
  run: |
    docker run --cpu-shares ${{ vars.CPU_SHARES || '1024' }} -d myimage

In Python with docker-py:

python
import docker
client = docker.from_env()

# Ensure integer type
cpu_shares = int(os.environ.get('CPU_SHARES', 1024))
if cpu_shares < 2:
    cpu_shares = 1024

container = client.containers.run(
    'myimage',
    cpu_shares=cpu_shares,
    detach=True
)
6Verify cgroup driver compatibility

CPU shares require proper cgroup support. Check your Docker daemon configuration:

bash
# Check cgroup driver
docker info | grep -i cgroup

# Expected output for cgroup v1 or v2
Cgroup Driver: cgroupfs
# or
Cgroup Driver: systemd

If you see "none" as the cgroup driver:

This can happen in rootless Docker or WSL environments. In these cases, CPU shares may not be supported:

bash
# WSL users may see warnings like:
# WARNING: No cpu shares support

Solutions:
1. For WSL2: Ensure you're using the WSL2 backend in Docker Desktop
2. For rootless Docker: Ensure systemd and cgroup v2 are properly configured
3. Consider using --cpus flag instead for hard CPU limits:

bash
# Alternative: use --cpus for hard limits
docker run --cpus 0.5 -d myimage  # Limit to half a CPU

Advanced notes

Understanding CPU Shares vs Other CPU Controls:

Docker offers multiple ways to control CPU resources:

| Option | Purpose | Example |
|--------|---------|---------|
| --cpu-shares | Relative weight (soft limit) | --cpu-shares 512 |
| --cpus | Limit number of CPUs (hard limit) | --cpus 1.5 |
| --cpuset-cpus | Pin to specific CPUs | --cpuset-cpus "0,1" |
| --cpu-period/quota | Fine-grained control | --cpu-quota 50000 |

CPU Shares Calculation Example:

If you have three containers:
- Container A: 1024 shares (default)
- Container B: 512 shares
- Container C: 512 shares

Total shares = 2048

When all containers are CPU-bound:
- Container A gets: 1024/2048 = 50% CPU
- Container B gets: 512/2048 = 25% CPU
- Container C gets: 512/2048 = 25% CPU

Multi-Core Behavior:

On multi-core systems, CPU shares are distributed across all cores. A container with fewer shares can still use 100% of available CPU if other containers aren't competing.

Docker Swarm Considerations:

In Docker Swarm mode, cpu_shares may be interpreted differently. Swarm has been known to interpret shares as "number of CPUs" rather than relative weight, which can cause scheduling failures if the value exceeds available CPUs.

Windows Containers:

CPU shares work differently on Windows containers. The --cpu-shares flag maps to Windows job object CPU rate control. Some CPU options like --cpuset-cpus are not supported on Windows and will produce "invalid option" errors.

Debugging CPU Share Issues:

bash
# Check container's CPU shares
docker inspect --format '{{.HostConfig.CpuShares}}' container_name

# Monitor CPU usage in real-time
docker stats --format "table {{.Name}}	{{.CPUPerc}}	{{.MemUsage}}"

# View cgroup settings directly (Linux)
cat /sys/fs/cgroup/cpu/docker/<container_id>/cpu.shares

Frequently asked questions

What does "Error response from daemon: invalid CPU shares" mean?
The "invalid CPU shares" error indicates that Docker cannot accept the CPU share value you provided. CPU shares in Docker control how much CPU time a container gets relative to other containers when CPU resources are constrained. The --cpu-shares (or -c) flag sets a relative weight for CPU scheduling.
How do I fix "Error response from daemon: invalid CPU shares"?
This Docker error occurs when you specify an invalid value for the --cpu-shares flag. CPU shares must be an integer value of 2 or higher (or 0 to use the default of 1024). The fix involves using a valid integer within the acceptable range.
What causes "Error response from daemon: invalid CPU shares"?
Using a CPU shares value of 1 (minimum valid value is 2) Passing a float/decimal value instead of an integer (e.g., 0.5 or 512.5) Providing a string instead of an integer (common when reading from .env files)
Is the "Error response from daemon: invalid CPU shares" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading