docker/cli · error

the -- flag requires that a -- flag and/or -- flag be…

Error message

the --%s flag requires that a --%s flag and/or --%s flag be provided as well

What it means

Thrown by 'docker swarm ca --rotate' when --ca-cert is given but neither --ca-key nor --external-ca is supplied. A rotation that sets a new CA certificate needs either the matching private key (to self-sign) or an external CA endpoint to sign with it.

Solutions

1. Add the matching key: 'docker swarm ca --rotate --ca-cert ./new.pem --ca-key ./new-key.pem'.
2. Or add an external CA spec: 'docker swarm ca --rotate --ca-cert ./new.pem --external-ca protocol=cfssl,url=https://ca'.
3. If you want Docker to generate a brand-new CA, drop --ca-cert entirely and run 'docker swarm ca --rotate'.

Example fix

# before
docker swarm ca --rotate --ca-cert ./new.pem

# after
docker swarm ca --rotate --ca-cert ./new.pem --ca-key ./new-key.pem

// Validate: --ca-cert on rotate needs --ca-key and/or --external-ca
if flags.Changed(flagRotate) && flags.Changed(flagCACert) && len(externalCA.Value()) == 0 && !flags.Changed(flagCAKey) {
    return errors.New("--ca-cert requires --ca-key and/or --external-ca")
}

func certProvidedWithoutSigner(flags *pflag.FlagSet, ext Value) bool {
	return flags.Changed(flagCACert) && len(ext.Value()) == 0 && !flags.Changed(flagCAKey)
}

When it happens

Trigger: Running 'docker swarm ca --rotate --ca-cert ./new.pem' with neither --ca-key nor --external-ca. The guard at ca.go:81 checks flags.Changed(flagCACert) && len(opts.externalCA.Value())==0 && !flags.Changed(flagCAKey).

Common situations: Operator supplies only the public cert half of a CA pair; assumes --ca-cert alone regenerates a key; forgot to copy the key file path.

Related errors

• no CA information available
• file contents must be in PEM format
• `-- ` flag requires the `--rotate` flag to update the CA
• rotating to an external CA requires the
• error reading from STDIN: data is empty

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

Appendix: source

Thrown at cli/command/swarm/ca.go:82

	}

	if !opts.rotate {
		for _, f := range []string{flagCACert, flagCAKey, flagCertExpiry, flagExternalCA} {
			if flags.Changed(f) {
				return fmt.Errorf("`--%s` flag requires the `--rotate` flag to update the CA", f)
			}
		}
		return displayTrustRoot(dockerCLI.Out(), res)
	}

	if flags.Changed(flagExternalCA) && len(opts.externalCA.Value()) > 0 && !flags.Changed(flagCACert) {
		return fmt.Errorf(
			"rotating to an external CA requires the `--%s` flag to specify the external CA's cert - "+
				"to add an external CA with the current root CA certificate, use the `update` command instead", flagCACert)
	}

	if flags.Changed(flagCACert) && len(opts.externalCA.Value()) == 0 && !flags.Changed(flagCAKey) {
		return fmt.Errorf("the --%s flag requires that a --%s flag and/or --%s flag be provided as well",
			flagCACert, flagCAKey, flagExternalCA)
	}

	updateSwarmSpec(&res.Swarm.Spec, flags, opts)
	if _, err := apiClient.SwarmUpdate(ctx, client.SwarmUpdateOptions{
		Version: res.Swarm.Version,
		Spec:    res.Swarm.Spec,
	}); err != nil {
		return err
	}

	if opts.detach {
		return nil
	}
	return attach(ctx, dockerCLI, opts)
}

func updateSwarmSpec(spec *swarm.Spec, flags *pflag.FlagSet, opts caOptions) {

View on GitHub (pinned to 4f84911bfe)