nats-io/nats-server · error

cert match by type not implemented

Error message

cert match by type not implemented

What it means

ErrBadMatchByType is returned when a cert_match_by string cannot be mapped to a CERT_MATCH_BY constant, or when TLSConfig is given a match-by type the platform implementation does not handle. ParseCertMatchBy validates against MatchByMap; the Windows TLSConfig dispatch rejects unmatched types.

Source

Thrown at server/certstore/errors.go:54

	ErrExtractingPublicKey = errors.New("unable to extract public key from store")

	// ErrBadPublicKeyAlgorithm represents a bad or unsupported public key algorithm
	ErrBadPublicKeyAlgorithm = errors.New("unsupported public key algorithm")

	// ErrExtractPropertyFromKey represents a general failure to extract a metadata property field
	ErrExtractPropertyFromKey = errors.New("unable to extract property from key")

	// ErrBadECCCurveName represents an ECC signature curve name that is bad or unsupported
	ErrBadECCCurveName = errors.New("unsupported ECC curve name")

	// ErrFailedCertSearch represents not able to find certificate in store
	ErrFailedCertSearch = errors.New("unable to find certificate in store")

	// ErrFailedX509Extract represents not being able to extract x509 certificate from found cert in store
	ErrFailedX509Extract = errors.New("unable to extract x509 from certificate")

	// ErrBadMatchByType represents unknown CERT_MATCH_BY passed
	ErrBadMatchByType = errors.New("cert match by type not implemented")

	// ErrBadCertStore represents unknown CERT_STORE passed
	ErrBadCertStore = errors.New("cert store type not implemented")

	// ErrConflictCertFileAndStore represents ambiguous configuration of both file and store
	ErrConflictCertFileAndStore = errors.New("'cert_file' and 'cert_store' may not both be configured")

	// ErrBadCertStoreField represents malformed cert_store option
	ErrBadCertStoreField = errors.New("expected 'cert_store' to be a valid non-empty string")

	// ErrBadCertMatchByField represents malformed cert_match_by option
	ErrBadCertMatchByField = errors.New("expected 'cert_match_by' to be a valid non-empty string")

	// ErrBadCertMatchField represents malformed cert_match option
	ErrBadCertMatchField = errors.New("expected 'cert_match' to be a valid non-empty string")

	// ErrBadCaCertMatchField represents malformed cert_match option
	ErrBadCaCertMatchField = errors.New("expected 'ca_certs_match' to be a valid non-empty string array")

View on GitHub (pinned to 3a66a489d2)

Solutions

  1. Set cert_match_by to a supported value — check the library's MatchByMap (e.g. 'thumbprint', 'subject') and fix spelling.
  2. Remove leading/trailing whitespace from cert_match_by in the config file.
  3. Confirm the platform build supports the chosen match type (Windows implementation covers only its switch cases).
  4. If you need another matching strategy, match by subject or upgrade to a version adding it.

Example fix

// before
cert_match_by: "sha1_thumbprint"
// after
cert_match_by: "thumbprint"
Defensive patterns

Strategy: validation

Validate before calling

switch strings.ToLower(cfg.CertMatchBy) {
case "thumbprint", "subject":
    // supported
default:
    return fmt.Errorf("cert_match_by must be thumbprint or subject, got %q", cfg.CertMatchBy)
}

Type guard

func isBadMatchByErr(err error) bool { return errors.Is(err, certstore.ErrBadMatchByType) }

Try / catch

_, err := certstore.ParseCertMatchBy(cfg.CertMatchBy)
if errors.Is(err, certstore.ErrBadMatchByType) {
    // fix config before starting server
}

Prevention

When it happens

Trigger: certstore.go:83 — ParseCertMatchBy(certMatchBy) with a string not in MatchByMap (after lowercasing); certstore_windows.go:235 — TLSConfig encounters a parsed match type not implemented in the windows switch (thumbprint/subject only).

Common situations: Config typo like cert_match_by: "Thumbprint " (extra space is fine after ToLower, but "sha1", "serial" etc. are unsupported), or copying match_by values from another product's config format.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/354343f4ebab53c1. Report an issue: GitHub.