docker/cli · error

invalid field in secret request: {key}

Error message

invalid field in secret request: {key}

What it means

Thrown by SecretOpt.Set when a key=value field in a --secret request uses a key that is not one of source, src, target, uid, gid, mode. The switch statement falls to the default branch and rejects the unknown key verbatim.

Source

Thrown at opts/swarmopts/secret.go:66

		// TODO(thaJeztah): these options should not be case-insensitive.
		switch strings.ToLower(key) {
		case "source", "src":
			options.SecretName = val
		case "target":
			options.File.Name = val
		case "uid":
			options.File.UID = val
		case "gid":
			options.File.GID = val
		case "mode":
			m, err := strconv.ParseUint(val, 0, 32)
			if err != nil {
				return fmt.Errorf("invalid mode specified: %v", err)
			}

			options.File.Mode = os.FileMode(m)
		default:
			return errors.New("invalid field in secret request: " + key)
		}
	}

	if options.SecretName == "" {
		return errors.New("source is required")
	}
	if options.File.Name == "" {
		options.File.Name = options.SecretName
	}

	o.values = append(o.values, options)
	return nil
}

// Type returns the type of this option
func (*SecretOpt) Type() string {
	return "secret"
}

View on GitHub (pinned to 4f84911bfe)

Solutions

1. Use only recognized keys: source/src, target, uid, gid, mode.
2. Rename any 'name' field to 'source'.
3. Use the short form --secret <secretname> when no overrides are needed.

Example fix

// before
--secret name=dbpw,target=/run/secrets/pw
// after
--secret source=dbpw,target=/run/secrets/pw

validSecretKeys := map[string]bool{"source": true, "src": true, "target": true, "uid": true, "gid": true, "mode": true}
for _, f := range strings.Split(spec, ",") {
    k, _, _ := strings.Cut(strings.ToLower(f), "=")
    if !validSecretKeys[k] {
        return fmt.Errorf("unknown secret field %q", k)
    }
}

if err := secretOpt.Set(spec); err != nil {
    return err
}

When it happens

Trigger: Passing --secret name=dbpw, or --secret file=/run/secrets/x, or any field with an unrecognized key.

Common situations: Confusing secret option keys with config keys, or assuming extra fields like 'name' or 'file' are accepted. Also case differences are tolerated (keys are lowercased), but unknown keys are not.

Related errors

• source is required
• source is required
• hostip is not supported
• error reading from STDIN: data is empty
• config file is required

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