docker/compose · error

label must be set as KEY=VALUE

Error message

label must be set as KEY=VALUE

What it means

Each `--label` argument to `docker compose run` must be a KEY=VALUE pair. The parsing loop uses strings.Cut on the first '='; if the argument contains no '=' at all the error is returned immediately (empty values like KEY= are allowed and become an empty label value).

Source

Thrown at cmd/compose/run.go:306

	project, err := options.apply(project)
	if err != nil {
		return err
	}

	err = createOpts.Apply(project)
	if err != nil {
		return err
	}

	if err := checksForRemoteStack(ctx, dockerCli, project, buildOpts, createOpts.AssumeYes, []string{}); err != nil {
		return err
	}

	labels := types.Labels{}
	for _, s := range options.labels {
		key, val, ok := strings.Cut(s, "=")
		if !ok {
			return fmt.Errorf("label must be set as KEY=VALUE")
		}
		labels[key] = val
	}

	var buildForRun *api.BuildOptions
	if !createOpts.noBuild {
		bo, err := buildOpts.toAPIBuildOptions(nil)
		if err != nil {
			return err
		}
		buildForRun = &bo
	}

	environment, err := options.getEnvironment(project.Environment.Resolve)
	if err != nil {
		return err
	}

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Write labels as `--label KEY=VALUE`, e.g. `--label com.example.owner=alice`.
2. Quote the whole pair in one argv token: `--label "key=$VALUE"`.
3. Remember `--label` is repeatable — one flag per label, not a comma-separated list.

Example fix

# before
docker compose run --label com.example.owner alice web

# after
docker compose run --label com.example.owner=alice web

# bash: validate each label is KEY=VALUE
for l in "${LABELS[@]}"; do
  [[ "$l" == *=* ]] || { echo "label must be KEY=VALUE: '$l'" >&2; exit 2; }
done
docker compose run "${LABELS[@]/#/--label }" web

When it happens

Trigger: Running `docker compose run --label com.example.tag web` (missing =VALUE), or quoting errors that strip the `=value` part, e.g. `--label "com.example.tag"` where the value ended up in a separate argv slot.

Common situations: Passing labels from unquoted/unset variables (`--label mylabel=${TAG}` is fine when set, but building the whole KEY=VALUE by concatenation can drop the '=' part); habits from `docker run --label key value` (space form) which compose does not accept.

Related errors

• invalid --scale option %q. Should be SERVICE=NUM
• --service-ports and --publish are incompatible
• --tty and --no-tty can't be used together
• cannot specify DEPRECATED "--no-ansi" and "--ansi". Please u
• cannot specify DEPRECATED "--workdir" and "--project-directo

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