conflicting options: cannot specify a volume-name through…

Error message

conflicting options: cannot specify a volume-name through both --name and as a positional arg

What it means

Returned by 'docker volume create' when the volume name is supplied both via the hidden --name flag AND as a positional argument. The command accepts at most one positional arg (VOLUME), and at create.go:57-59 it checks: if a positional arg was given and options.name is already non-empty, the two sources conflict and the command aborts. Only one way of naming the volume is allowed.

Solutions

Drop the --name flag and pass the volume name only as the trailing positional: 'docker volume create myvol'.
If you must keep --name, ensure no positional volume argument follows it.
Audit the script/alias that assembles the command for accidental double-specification of the name.

Example fix

# before
docker volume create --name mydata mydata

# after
docker volume create mydata

Defensive patterns

Strategy: validation

Validate before calling

// Build a 'docker volume create' arg list ensuring name is set exactly once.
func buildVolumeCreateArgs(name string, opts []string) []string {
    args := []string{"volume", "create"}
    // Do NOT also append name positionally if you set --name; choose one form.
    args = append(args, "--name", name)
    args = append(args, opts...)
    return args // never append name again as positional
}

Prevention

Standardize on the positional form ('docker volume create <name>') in all scripts; avoid the hidden --name.
Unit-test wrapper scripts that assemble create commands to assert the name appears once.
Run 'docker volume create --help' to confirm which flags your CLI version exposes.

When it happens

Trigger: Running 'docker volume create --name myvol myvol2' (both --name and a trailing positional). The --name flag is hidden (create.go:71), so this typically arises from scripts or completion tools that set --name and also append the name positionally.

Common situations: Wrapper scripts/Makefiles that build the create command by concatenating '--name $N' and '$N'. Shell aliases or completion helpers that inject --name. Migrating from an older tool that emitted --name where the modern CLI expects a positional.

Related errors

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

Appendix: source

Thrown at cli/command/volume/create.go:58

}

func newCreateCommand(dockerCLI command.Cli) *cobra.Command {
	options := createOptions{
		driverOpts:        *opts.NewMapOpts(nil, nil),
		labels:            opts.NewListOpts(opts.ValidateLabel),
		secrets:           *opts.NewMapOpts(nil, nil),
		requisiteTopology: opts.NewListOpts(nil),
		preferredTopology: opts.NewListOpts(nil),
	}

	cmd := &cobra.Command{
		Use:   "create [OPTIONS] [VOLUME]",
		Short: "Create a volume",
		Args:  cli.RequiresMaxArgs(1),
		RunE: func(cmd *cobra.Command, args []string) error {
			if len(args) == 1 {
				if options.name != "" {
					return errors.New("conflicting options: cannot specify a volume-name through both --name and as a positional arg")
				}
				options.name = args[0]
			}
			options.cluster = hasClusterVolumeOptionSet(cmd.Flags())
			return runCreate(cmd.Context(), dockerCLI, options)
		},
		ValidArgsFunction:     cobra.NoFileCompletions,
		DisableFlagsInUseLine: true,
	}
	flags := cmd.Flags()
	flags.StringVarP(&options.driver, "driver", "d", "local", "Specify volume driver name")
	flags.StringVar(&options.name, "name", "", "Specify volume name")
	flags.Lookup("name").Hidden = true
	flags.VarP(&options.driverOpts, "opt", "o", "Set driver specific options")
	flags.Var(&options.labels, "label", "Set metadata for a volume")

	// flags for cluster volumes only
	flags.StringVar(&options.group, "group", "", "Cluster Volume group (cluster volumes)")

View on GitHub (pinned to 4f84911bfe)