docker/cli · error

when using secret driver secret data must be empty

Error message

when using secret driver secret data must be empty

What it means

Raised by runSecretCreate (cli/command/secret/create.go:77) when `docker secret create` is invoked with a --driver but a secret data source (file argument, including '-' for stdin) is also provided. With a secret driver, the secret value is produced by the driver plugin at container-start time, so the Swarm secret spec must carry an empty Data field — supplying inline data would be contradictory.

Source

Thrown at cli/command/secret/create.go:77

		DisableFlagsInUseLine: true,
	}
	flags := cmd.Flags()
	flags.VarP(&options.labels, "label", "l", "Secret labels")
	flags.StringVarP(&options.driver, "driver", "d", "", "Secret driver")
	flags.SetAnnotation("driver", "version", []string{"1.31"})
	flags.StringVar(&options.templateDriver, "template-driver", "", "Template driver")
	flags.SetAnnotation("template-driver", "version", []string{"1.37"})

	return cmd
}

func runSecretCreate(ctx context.Context, dockerCLI command.Cli, options createOptions) error {
	apiClient := dockerCLI.Client()

	var secretData []byte
	if options.driver != "" {
		if options.file != "" {
			return errors.New("when using secret driver secret data must be empty")
		}
	} else {
		var err error
		secretData, err = readSecretData(dockerCLI.In(), options.file)
		if err != nil {
			return err
		}
	}

	spec := swarm.SecretSpec{
		Annotations: swarm.Annotations{
			Name:   options.name,
			Labels: opts.ConvertKVStringsToMap(options.labels.GetSlice()),
		},
		Data: secretData,
	}
	if options.driver != "" {
		spec.Driver = &swarm.Driver{

View on GitHub (pinned to e9452d6e78)

Solutions

1. Drop the file/stdin argument when using a driver: docker secret create --driver my-driver my_secret
2. If you actually have literal secret data, remove --driver and pass the file or stdin: docker secret create my_secret ./secret.txt
3. If you meant Go/EJS templating of secret content, use --template-driver instead of --driver (template-driver still takes secret data)

Example fix

# before
echo "supersecret" | docker secret create --driver vault my_secret -

# after (driver-managed: no data)
docker secret create --driver vault my_secret
# or (literal data: no driver)
echo "supersecret" | docker secret create my_secret -

When it happens

Trigger: docker secret create --driver <plugin> <name> <file>, or docker secret create --driver <plugin> <name> - (stdin marker sets options.file to '-'). Any non-empty file argument combined with a non-empty --driver hits this check before the API call.

Common situations: Users adopting a secrets plugin (e.g. a Vault-backed driver) and keeping their old file-based create syntax; scripts that always append '-' and pipe data, then later add --driver; confusion between --driver (secret value provider) and --template-driver (templating of the secret contents), which have different data rules.

Related errors

• error reading from STDIN: data is empty
• secret file is required
• --pid: invalid PID mode
• --uts: invalid UTS mode
• --userns: invalid USER mode

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/0fa32e9cbc221285.json. Report an issue: GitHub.