docker/compose · error

%s must be an integer (found: %q)

Error message

%s must be an integer (found: %q)

What it means

The COMPOSE_PARALLEL_LIMIT environment variable caps concurrency for compose operations. During startup, if the flag --parallel was not set, compose parses the env var with strconv.Atoi; a non-numeric value (including empty or trailing whitespace/garbage) aborts command initialization before anything runs.

Source

Thrown at cmd/compose/compose.go:549

					}
					opts.EnvFiles[i] = file
				} else {
					opts.EnvFiles[i] = file
				}
			}

			composeCmd := cmd
			for composeCmd.Name() != PluginName {
				if !composeCmd.HasParent() {
					return fmt.Errorf("error parsing command line, expected %q", PluginName)
				}
				composeCmd = composeCmd.Parent()
			}

			if v, ok := os.LookupEnv(ComposeParallelLimit); ok && !composeCmd.Flags().Changed("parallel") {
				i, err := strconv.Atoi(v)
				if err != nil {
					return fmt.Errorf("%s must be an integer (found: %q)", ComposeParallelLimit, v)
				}
				parallel = i
			}
			if parallel > 0 {
				logrus.Debugf("Limiting max concurrency to %d jobs", parallel)
				backendOptions.Add(compose.WithMaxConcurrency(parallel))
			}

			// dry run detection
			if dryRun {
				backendOptions.Add(compose.WithDryRun)
			}
			return nil
		},
	}

	c.AddCommand(
		upCommand(&opts, dockerCli, backendOptions),

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Set a plain integer: `export COMPOSE_PARALLEL_LIMIT=4`
2. Unset it if the default concurrency is fine: `unset COMPOSE_PARALLEL_LIMIT`
3. Or bypass the env entirely with `--parallel N` on the command line (a changed flag skips the env parse)

Example fix

# before
export COMPOSE_PARALLEL_LIMIT="4 workers"
# after
export COMPOSE_PARALLEL_LIMIT=4

if [ -n "${COMPOSE_PARALLEL_LIMIT:-}" ]; then
  case "$COMPOSE_PARALLEL_LIMIT" in
    ''|*[!0-9]*) echo "COMPOSE_PARALLEL_LIMIT must be an integer" >&2; exit 2;;
  esac
fi
docker compose up

When it happens

Trigger: COMPOSE_PARALLEL_LIMIT=4x, =high, =' 4', or exported as empty-but-set, while running any compose command that triggers the root PersistentPreRunE, without an explicit --parallel flag.

Common situations: Typos in CI env configuration; values copied from docs with units ('4 workers'); export COMPOSE_PARALLEL_LIMIT without a value in shell profiles; secrets managers injecting the variable as an empty string.

Related errors

• source can not be empty
• destination can not be empty
• invalid filter '${filter}'
• --index requires one service to be selected
• arguments to --filter should be in form KEY=VAL

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