docker/cli · error

the external-ca option needs a protocol= parameter

Error message

the external-ca option needs a protocol= parameter

What it means

Returned by parseExternalCA when an `--external-ca` specification is parsed and no `protocol=` key was present among its comma-separated key=value fields. The protocol (currently only "cfssl" is recognized) is mandatory because the swarm manager must know how to talk to the external signing endpoint.

Source

Thrown at cli/command/swarm/opts.go:210

		case "url":
			hasURL = true
			externalCA.URL = value
		case "cacert":
			cacontents, err := os.ReadFile(value)
			if err != nil {
				return nil, fmt.Errorf("unable to read CA cert for external CA: %w", err)
			}
			if pemBlock, _ := pem.Decode(cacontents); pemBlock == nil {
				return nil, errors.New("CA cert for external CA must be in PEM format")
			}
			externalCA.CACert = string(cacontents)
		default:
			externalCA.Options[key] = value
		}
	}

	if !hasProtocol {
		return nil, errors.New("the external-ca option needs a protocol= parameter")
	}
	if !hasURL {
		return nil, errors.New("the external-ca option needs a url= parameter")
	}

	return &externalCA, nil
}

func addSwarmCAFlags(flags *pflag.FlagSet, options *swarmCAOptions) {
	flags.DurationVar(&options.nodeCertExpiry, flagCertExpiry, 90*24*time.Hour, "Validity period for node certificates (ns|us|ms|s|m|h)")
	flags.Var(&options.externalCA, flagExternalCA, "Specifications of one or more certificate signing endpoints")
}

func addSwarmFlags(flags *pflag.FlagSet, options *swarmOptions) {
	flags.Int64Var(&options.taskHistoryLimit, flagTaskHistoryLimit, 5, "Task history retention limit")
	flags.DurationVar(&options.dispatcherHeartbeat, flagDispatcherHeartbeat, 5*time.Second, "Dispatcher heartbeat period (ns|us|ms|s|m|h)")
	flags.Uint64Var(&options.maxSnapshots, flagMaxSnapshots, 0, "Number of additional Raft snapshots to retain")
	flags.SetAnnotation(flagMaxSnapshots, "version", []string{"1.25"})

View on GitHub (pinned to e9452d6e78)

Solutions

1. Add `protocol=cfssl` to the spec: `--external-ca protocol=cfssl,url=https://ca.example.com`.
2. Quote the whole spec so the shell doesn't split it: `--external-ca "protocol=cfssl,url=..."`.
3. Note cfssl is the only accepted protocol value; anything else fails with 'unrecognized external CA protocol'.

Example fix

# before
docker swarm update --external-ca url=https://ca.example.com
# after
docker swarm update --external-ca protocol=cfssl,url=https://ca.example.com

When it happens

Trigger: `docker swarm init` or `docker swarm update` with `--external-ca` where the CSV spec omits protocol, e.g. `--external-ca url=https://ca.example.com` or a spec where the protocol field was mangled by shell quoting so it never parsed as `protocol=...`.

Common situations: Copy-pasting a partial example from docs; shell splitting on commas so only the first field reaches the flag; templated deployment scripts leaving the protocol variable empty.

Related errors

• the external-ca option needs a url= parameter
• unknown role %s
• file contents must be in PEM format
• CA cert for external CA must be in PEM format
• node ID not found in /info

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