docker/cli · error

file contents must be in PEM format

Error message

file contents must be in PEM format

What it means

Raised by the PEMFile flag type's Set method when the file passed to a certificate/key flag (e.g. `--ca-cert` or `--ca-key` on `docker swarm ca`) reads successfully but pem.Decode finds no PEM block in it. The CLI validates client-side that the file contains at least one `-----BEGIN ...-----` block before sending it to the daemon.

Source

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

// Type returns the type of this option.
func (*PEMFile) Type() string {
	return "pem-file"
}

// String returns the path to the pem file
func (p *PEMFile) String() string {
	return p.path
}

// Set parses a root rotation option
func (p *PEMFile) Set(value string) error {
	contents, err := os.ReadFile(value)
	if err != nil {
		return err
	}
	if pemBlock, _ := pem.Decode(contents); pemBlock == nil {
		return errors.New("file contents must be in PEM format")
	}
	p.contents, p.path = string(contents), value
	return nil
}

// Contents returns the contents of the PEM file
func (p *PEMFile) Contents() string {
	return p.contents
}

// parseExternalCA parses an external CA specification from the command line,
// such as protocol=cfssl,url=https://example.com.
func parseExternalCA(caSpec string) (*swarm.ExternalCA, error) {
	csvReader := csv.NewReader(strings.NewReader(caSpec))
	fields, err := csvReader.Read()
	if err != nil {
		return nil, err
	}

View on GitHub (pinned to e9452d6e78)

Solutions

1. Inspect the file — it must start with a `-----BEGIN CERTIFICATE-----` (or similar) header.
2. Convert DER to PEM: `openssl x509 -inform der -in cert.der -out cert.pem`.
3. Extract from PKCS#12: `openssl pkcs12 -in bundle.p12 -out cert.pem -nokeys`.
4. Check for an empty file or wrong path passed to the flag.

Example fix

# before
docker swarm ca --rotate --ca-cert cert.der --ca-key key.pem
# after
openssl x509 -inform der -in cert.der -out cert.pem
docker swarm ca --rotate --ca-cert cert.pem --ca-key key.pem

When it happens

Trigger: Passing a file to a pem-file flag whose contents are not PEM: a DER-encoded certificate, a PKCS#12 (.pfx/.p12) bundle, an empty file, a file with Windows BOM/encoding corruption, or accidentally passing the wrong path (e.g. a config file).

Common situations: Exporting certificates from Windows tooling in DER/PKCS#12 format instead of PEM; copy-pasting a cert and losing the BEGIN/END header lines; pointing the flag at the key when both cert and key live in differently formatted files.

Related errors

• CA cert for external CA must be in PEM format
• the external-ca option needs a protocol= parameter
• the external-ca option needs a url= parameter
• node ID not found in /info
• cannot supply extra formatting options to the pretty templat

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