docker/compose · error

unsupported --progress value %q

Error message

unsupported --progress value %q

What it means

The value passed to `--progress` does not match any supported display mode. Compose's mode selector accepts auto, tty, plain, quiet (or "none"), and json; anything else falls into the default branch of the switch and is rejected with the offending value echoed back.

Source

Thrown at cmd/compose/compose.go:688

			return nil, fmt.Errorf("can't use --progress tty while ANSI support is disabled")
		}
		display.Mode = display.ModeTTY
		return display.Full(dockerCli.Err(), stdinfo(dockerCli), detached), nil
	case display.ModePlain:
		if ansi == "always" {
			return nil, fmt.Errorf("can't use --progress plain while ANSI support is forced")
		}
		display.Mode = display.ModePlain
		return display.Plain(dockerCli.Err()), nil
	case display.ModeQuiet, "none":
		display.Mode = display.ModeQuiet
		return display.Quiet(), nil
	case display.ModeJSON:
		display.Mode = display.ModeJSON
		logrus.SetFormatter(&logrus.JSONFormatter{})
		return display.JSON(dockerCli.Err()), nil
	default:
		return nil, fmt.Errorf("unsupported --progress value %q", progress)
	}
}

func setEnvWithDotEnv(opts ProjectOptions, dockerCli command.Cli) error {
	// Check if we're using a remote config (OCI or Git)
	// If so, skip env loading as remote loaders haven't been initialized yet
	// and trying to process the path would fail
	remoteLoaders := opts.remoteLoaders(dockerCli)
	for _, path := range opts.ConfigPaths {
		for _, loader := range remoteLoaders {
			if loader.Accept(path) {
				// Remote config - skip env loading for now
				// It will be loaded later when the project is fully initialized
				return nil
			}
		}
	}

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Use one of the accepted values: auto, tty, plain, quiet (or none), json.
2. If the value comes from a variable, echo it before running compose to catch empty/typo values.
3. Upgrade scripts that use values valid only in other Docker tooling (e.g. buildx's --progress rawjson is not valid here).

Example fix

# before
docker compose --progress ${PROGRESS_MODE} up  # PROGRESS_MODE=""

# after
docker compose --progress "${PROGRESS_MODE:-auto}" up

# bash
progress="${COMPOSE_PROGRESS:-auto}"
case "$progress" in auto|tty|plain|quiet|none|json) ;; *) echo "bad progress: $progress" >&2; exit 2;; esac
docker compose --progress "$progress" up -d

When it happens

Trigger: Running e.g. `docker compose --progress silent up` or a typo like `--progress json ` (trailing space), `--progres=plain` (unknown flag), or passing a value from a script variable that is empty or misspelled.

Common situations: CI pipelines parameterizing --progress with a variable that is empty or contains a typo; copy-paste from older docker compose versions whose accepted values differed; setting COMPOSE_PROGRESS to an invalid string.

Related errors

• --index requires one service to be selected
• cannot combine --attach and --attach-dependencies
• can't use --progress plain while ANSI support is forced
• unsupported format %q
• invalid --pull option %q

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