docker/cli · error

source is required

Error message

source is required

What it means

Thrown by SecretOpt.Set when a key=value --secret spec omits the source/src key. A Swarm secret reference requires a source secret name; the parser validates this after all fields are consumed. The short form (--secret foo) auto-sets source and never hits this.

Solutions

1. Add source=<secretname> (or src=) to the --secret spec.
2. Use the short form --secret <secretname> when no other overrides are needed.
3. Confirm the secret exists with docker secret ls before referencing it.

Example fix

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

hasSource := false
for _, f := range strings.Split(spec, ",") {
    k, _, _ := strings.Cut(strings.ToLower(f), "=")
    if k == "source" || k == "src" {
        hasSource = true
    }
}
if !hasSource && !(len(strings.Split(spec, ",")) == 1 && !strings.Contains(spec, "=")) {
    return errors.New("secret spec requires source=")
}

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

When it happens

Trigger: Passing --secret target=/run/secrets/pw,uid=33 without a source=, or any secret spec missing the secret name.

Common situations: Assuming target alone names the secret, or a partial spec where the source field was dropped during edits.

Related errors

• invalid field in secret request
• 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/f58167f088516128. Report an issue: GitHub.

Appendix: source

Thrown at opts/swarmopts/secret.go:71

			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"
}

// String returns a string repr of this option
func (o *SecretOpt) String() string {
	secrets := make([]string, 0, len(o.values))
	for _, secret := range o.values {

View on GitHub (pinned to 4f84911bfe)