invalid scale specifier: can't parse replica value as int: %

Error message

invalid scale specifier: can't parse replica value as int: %v

What it means

Thrown by parseServicesReplicasArgs in `docker compose scale` when the SERVICE=REPLICAS argument is well-formed but the replica value fails strconv.Atoi. The message helpfully embeds the whole offending arg, so the exact token that failed to parse is visible. Only plain base-10 integers are accepted (an optional sign followed by digits); floats, scientific notation, or suffixes like '2x' are rejected.

Source

Thrown at cmd/compose/scale.go:123

	service, err := project.GetService(name)
	if err != nil {
		return err
	}
	service.SetScale(replicas)
	project.Services[name] = service
	return nil
}

func parseServicesReplicasArgs(args []string) (map[string]int, error) {
	serviceReplicaTuples := map[string]int{}
	for _, arg := range args {
		key, val, ok := strings.Cut(arg, "=")
		if !ok || key == "" || val == "" {
			return nil, fmt.Errorf("invalid scale specifier: %s", arg)
		}
		intValue, err := strconv.Atoi(val)
		if err != nil {
			return nil, fmt.Errorf("invalid scale specifier: can't parse replica value as int: %v", arg)
		}
		serviceReplicaTuples[key] = intValue
	}
	return serviceReplicaTuples, nil
}

View on GitHub (pinned to ddc4b044b6)

Solutions

Use a plain integer: `docker compose scale web=3`.
If the count comes from a script, round/convert it to an integer first (e.g. `printf '%.0f'`, `${COUNT//[[:space:]]/}`).
Verify the exact token in the error message — it shows the full arg including the value that failed Atoi.

Example fix

# before
docker compose scale web=$REPLICAS   # REPLICAS=2.0

# after
REPLICAS=$(printf '%.0f' "$REPLICAS")
docker compose scale web=$REPLICAS

Defensive patterns

Strategy: validation

Validate before calling

if ! [[ "$VAL" =~ ^-?[0-9]+$ ]]; then echo "replicas must be an integer: $VAL" >&2; exit 2; fi
docker compose scale "web=$VAL"

Prevention

Round floats before passing: printf '%.0f'.
Strip whitespace from computed counts.
Validate with a regex ^-?[0-9]+$ in wrappers.

When it happens

Trigger: Running `docker compose scale web=2.0`, `web=1e3`, `web=three`, or a value with whitespace like `web= 2` (leading space after '='). Also `scale web=08x` or values containing unit suffixes. Any single failure aborts the entire scale command before the project is loaded.

Common situations: Scripts computing a replica count and passing a float (e.g. output of a division like `4/2` in bc, or a Terraform/Ansible variable typed as float); passing a percentage or a human-written count like '~2'; whitespace introduced by variable expansion `scale web=${COUNT}` where COUNT=' 2'.

Related errors

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/b905e52bdc25d0f7. Report an issue: GitHub.