docker/compose · error

invalid --scale option %q. Should be SERVICE=NUM

Error message

invalid --scale option %q. Should be SERVICE=NUM

What it means

Each `--scale SERVICE=NUM` argument must contain an `=` with a non-empty numeric right side. applyScaleOpts uses strings.Cut on the first `=`; if there is no `=` or the value part is empty, the argument is rejected with this message before strconv.Atoi is attempted.

Source

Thrown at cmd/compose/create.go:203

		}
	}

	if err := applyPlatforms(project, true); err != nil {
		return err
	}

	err := applyScaleOpts(project, opts.scale)
	if err != nil {
		return err
	}
	return nil
}

func applyScaleOpts(project *types.Project, opts []string) error {
	for _, scale := range opts {
		name, val, ok := strings.Cut(scale, "=")
		if !ok || val == "" {
			return fmt.Errorf("invalid --scale option %q. Should be SERVICE=NUM", scale)
		}
		replicas, err := strconv.Atoi(val)
		if err != nil {
			return err
		}
		err = setServiceScale(project, name, replicas)
		if err != nil {
			return err
		}
	}
	return nil
}

var validPullPolicies = []string{
	types.PullPolicyAlways, types.PullPolicyNever, types.PullPolicyBuild,
	types.PullPolicyMissing, types.PullPolicyIfNotPresent,
}

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Write the argument as `--scale SERVICE=NUM`, e.g. `--scale web=3`.
2. Default the numeric variable: `--scale web=${REPLICAS:-1}` so the value is never empty.
3. Note the repeatable-flag form: pass `--scale` once per service, not a comma-separated list.

Example fix

# before
docker compose up --scale web=${REPLICAS}  # REPLICAS empty

# after
docker compose up --scale "web=${REPLICAS:-1}"

# bash: validate SERVICE=NUM before compose sees it
for s in "${SCALE_ARGS[@]}"; do
  [[ "$s" =~ ^[^=]+=[0-9]+$ ]] || { echo "bad --scale '$s' (want SERVICE=NUM)" >&2; exit 2; }
done
docker compose up "${SCALE_ARGS[@]/#/--scale }"

When it happens

Trigger: Passing `--scale web` (missing `=NUM`), `--scale web=` (empty value), or quoting mistakes such as `--scale "web = 3"` where the value becomes ` 3`/name `web ` or the cut leaves an empty tail.

Common situations: CI variables like `--scale web=${REPLICAS}` with REPLICAS unset producing `web=`; scripts building the arg by concatenation and dropping the value; users expecting space-separated `--scale web 3`.

Related errors

• --index requires one service to be selected
• cannot combine --attach and --attach-dependencies
• unsupported --progress value %q
• unsupported format %q
• invalid --pull option %q

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