docker/cli · error

secret file is required

Error message

secret file is required

What it means

Raised by readSecretData when the file argument to `docker secret create` is an empty string. The CLI requires either a real file path or "-" for STDIN; an empty filename means it has no source for the secret data, so it errors immediately rather than creating an empty secret.

Source

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

// readSecretData reads the secret from either stdin or the given fileName.
//
// It reads up to twice the maximum size of the secret ([maxSecretSize]),
// just in case swarm's limit changes; this is only a safeguard to prevent
// reading arbitrary files into memory.
func readSecretData(in io.Reader, fileName string) ([]byte, error) {
	switch fileName {
	case "-":
		data, err := io.ReadAll(io.LimitReader(in, 2*maxSecretSize))
		if err != nil {
			return nil, fmt.Errorf("error reading from STDIN: %w", err)
		}
		if len(data) == 0 {
			return nil, errors.New("error reading from STDIN: data is empty")
		}
		return data, nil
	case "":
		return nil, errors.New("secret file is required")
	default:
		// Open file with [FILE_FLAG_SEQUENTIAL_SCAN] on Windows, which
		// prevents Windows from aggressively caching it. We expect this
		// file to be only read once. Given that this is expected to be
		// a small file, this may not be a significant optimization, so
		// we could choose to omit this, and use a regular [os.Open].
		//
		// [FILE_FLAG_SEQUENTIAL_SCAN]: https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea#FILE_FLAG_SEQUENTIAL_SCAN
		f, err := sequential.Open(fileName)
		if err != nil {
			return nil, fmt.Errorf("error reading from %s: %w", fileName, err)
		}
		defer f.Close()
		data, err := io.ReadAll(io.LimitReader(f, 2*maxSecretSize))
		if err != nil {
			return nil, fmt.Errorf("error reading from %s: %w", fileName, err)
		}
		if len(data) == 0 {

View on GitHub (pinned to e9452d6e78)

Solutions

1. Pass a real file path: `docker secret create mysecret ./secret.txt`.
2. Use `-` explicitly if the data comes from STDIN.
3. In scripts, validate the variable before use: `: "${FILE:?secret file path required}"`.

Example fix

# before
docker secret create db_pass "$SECRET_FILE"   # SECRET_FILE empty
# after
: "${SECRET_FILE:?path to secret file required}"
docker secret create db_pass "$SECRET_FILE"

When it happens

Trigger: Invoking `docker secret create NAME ""` (empty string as the file argument), or programmatic/script invocations where the file-path variable expands to an empty string, e.g. `docker secret create name "$FILE"` with FILE unset.

Common situations: Shell scripts with unquoted or unset path variables, wrappers or Makefiles that template the file argument, and automation that builds the argv list dynamically and inserts an empty element.

Related errors

• error reading from STDIN: data is empty
• when using secret driver secret data must be empty
• placement preference must be of the format "<strategy>=<arg>
• invalid credential spec: value must be prefixed with "config
• container name cannot be empty

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