docker/cli · error

the external-ca option needs a url= parameter

Error message

the external-ca option needs a url= parameter

What it means

Returned by parseExternalCA when an `--external-ca` specification lacks a `url=` field. The URL identifies the external CA signing endpoint the swarm managers forward certificate signing requests to, so a spec without it is unusable.

Source

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

		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"})
	flags.Uint64Var(&options.snapshotInterval, flagSnapshotInterval, 10000, "Number of log entries between Raft snapshots")
	flags.SetAnnotation(flagSnapshotInterval, "version", []string{"1.25"})
	addSwarmCAFlags(flags, &options.swarmCAOptions)

View on GitHub (pinned to e9452d6e78)

Solutions

1. Include the endpoint: `--external-ca protocol=cfssl,url=https://ca.example.com`.
2. Quote the full spec to survive shell parsing.
3. Verify templated variables expand to a non-empty URL before invoking the CLI.

Example fix

# before
docker swarm update --external-ca protocol=cfssl
# 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 protocol=cfssl` (or any spec omitting url), or a spec where shell quoting/comma handling dropped the url field before it reached the flag parser.

Common situations: Unquoted specs split by the shell; automation templates with an empty URL variable; assuming the URL can be provided via a separate flag.

Related errors

• the external-ca option needs a protocol= 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/f74fc5e1a6ed0b82.json. Report an issue: GitHub.