docker/cli · error

invalid pull option: ' ': must be one of , or

Error message

invalid pull option: '%s': must be one of %q, %q or %q

What it means

Returned by validatePullOpt() when the --pull flag passed to `docker create`/`docker run` is not one of the recognized literals. The accepted values are defined as constants in create.go: "always", "missing" (the default), "never", or the empty string (meaning unset). Any other string is rejected before the container is created so that image-pull behavior stays well-defined.

Solutions

1. Set --pull to one of: always, missing, or never (or omit the flag, which is equivalent to missing).
2. If the value comes from a variable, default empty to "missing": --pull=${PULL:-missing}.
3. Check for typos such as --pull=Allways or --pull=mising.

Example fix

# before
docker run --pull yes nginx

# after
docker run --pull always nginx

var validPull = map[string]bool{"always": true, "missing": true, "never": true, "": true}
func validatePull(v string) error {
    if !validPull[v] {
        return fmt.Errorf("invalid pull option: %q (want always|missing|never)", v)
    }
    return nil
}
// call before invoking the run/create path with --pull

// Go CLI errors are returned, not thrown. Inspect the returned error and
// surface a usage hint:
if err := cmd.Execute(); err != nil {
    if strings.Contains(err.Error(), "invalid pull option") {
        fmt.Fprintln(os.Stderr, "--pull must be one of: always, missing, never")
    }
    os.Exit(1)
}

When it happens

Trigger: Passing `docker run --pull bogus nginx` or any value to the `--pull` flag that is not exactly "always", "missing", "never", or empty. The switch in validatePullOpt falls into the default branch and wraps the value in a fmt.Errorf.

Common situations: Typo in a script (e.g. --pull yes, --pull true, --pull all), copy-paste from docs that use non-canonical wording, or a wrapper that interpolates an unset variable producing an empty-but-quoted token.

Related errors

• invalid detach keys ( )
• failed to parse template
• is not a valid mac address
• invalid value: . Valid memory swappiness range is 0-100
• invalid range format for --expose

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/64f694dffbecaa7a. Report an issue: GitHub.

Appendix: source

Thrown at cli/command/container/create.go:388

		}); err != nil {
			response.Warnings = append(response.Warnings, fmt.Sprintf("injecting docker config.json into container failed: %v", err))
		}
	}
	for _, w := range response.Warnings {
		_, _ = fmt.Fprintln(dockerCLI.Err(), "WARNING:", w)
	}

	err = containerIDFile.Write(response.ID)
	return response.ID, err
}

func validatePullOpt(val string) error {
	switch val {
	case PullImageAlways, PullImageMissing, PullImageNever, "":
		// valid option, but nothing to do yet
		return nil
	default:
		return fmt.Errorf(
			"invalid pull option: '%s': must be one of %q, %q or %q",
			val,
			PullImageAlways,
			PullImageMissing,
			PullImageNever,
		)
	}
}

// copyDockerConfigIntoContainer takes the client configuration and copies it
// into the container.
//
// The path should be an absolute path in the container, commonly
// /root/.docker/config.json.
func copyDockerConfigIntoContainer(ctx context.Context, apiClient client.APIClient, containerID string, configPath string, config *configfile.ConfigFile) error {
	var configBuf bytes.Buffer
	if err := config.SaveToWriter(&configBuf); err != nil {
		return fmt.Errorf("saving creds: %w", err)

View on GitHub (pinned to 4f84911bfe)