docker/compose · error

invalid --pull option %q

Error message

invalid --pull option %q

What it means

The `--pull` flag on `docker compose create` (and commands reusing createOptions.Apply) accepts only the policies in validPullPolicies: always, missing, never, build. When `--pull` was explicitly set, Apply validates the value per service and rejects anything else.

Source

Thrown at cmd/compose/create.go:168

	}
	if opts.recreateDeps {
		return api.RecreateForce
	}
	return api.RecreateDiverged
}

func (opts createOptions) GetTimeout() *time.Duration {
	if opts.timeChanged {
		t := time.Duration(opts.timeout) * time.Second
		return &t
	}
	return nil
}

func (opts createOptions) Apply(project *types.Project) error {
	if opts.pullChanged {
		if !slices.Contains(validPullPolicies, opts.Pull) {
			return fmt.Errorf("invalid --pull option %q", opts.Pull)
		}
		for i, service := range project.Services {
			service.PullPolicy = opts.Pull
			project.Services[i] = service
		}
	}
	// N.B. opts.Build means "force build all", but images can still be built
	// when this is false
	// e.g. if a service has pull_policy: build or its local image is policy
	if opts.Build {
		for i, service := range project.Services {
			if service.Build == nil {
				continue
			}
			service.PullPolicy = types.PullPolicyBuild
			project.Services[i] = service
		}
	}

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Use one of: `--pull always`, `--pull missing`, `--pull never`, `--pull build` (note `policy` is only the flag's default display value, not an accepted explicit choice — check validPullPolicies in your version).
2. Default empty variables: `--pull "${PULL:-missing}"` and skip the flag entirely when unset.
3. Verify the exact accepted list with `docker compose create --help` for your installed version.

Example fix

# before
docker compose create --pull if-not-present

# after
docker compose create --pull missing

# bash
case "${PULL:-}" in "") ;; always|missing|never|build) PULL_FLAG=(--pull "$PULL");; *) echo "invalid pull policy: $PULL" >&2; exit 2;; esac
docker compose create "${PULL_FLAG[@]}"

When it happens

Trigger: Running `docker compose create --pull if-not-present` (a `docker run` value) or `--pull always ` with a typo/empty value from a variable. The check only runs when the flag was explicitly changed (opts.pullChanged).

Common situations: Copying `--pull if-not-present` habits from `docker run`; empty CI variables expanding to `--pull ""`; older compose versions accepting different policy strings.

Related errors

• --index requires one service to be selected
• cannot combine --attach and --attach-dependencies
• unsupported --progress value %q
• unsupported format %q
• --build and --no-build are incompatible

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