What causes "certificate not pinned" in nats-io/nats-server?

Update the configured pin to the peer's current certificate

certificate not pinned

Error message

certificate not pinned

What it means

TLS handshake check: the peer's presented certificate chain does not match the certificate pin(s) configured for this connection (matchesPinnedCert failed), so the handshake is rejected. The peer's certificate and the configured pin are the mismatched inputs.

Source

Thrown at server/errors.go:213

	ErrClusterNameRemoteConflict = errors.New("cluster name from remote server conflicts")

	// ErrClusterNameHasSpaces signals that the cluster name contains spaces, which is not allowed.
	ErrClusterNameHasSpaces = errors.New("cluster name cannot contain spaces")

	// ErrClusterNameReserved signals that the cluster name is reserved for internal protocol use.
	ErrClusterNameReserved = errors.New("cluster name is reserved")

	// ErrMalformedSubject is returned when a subscription is made with a subject that does not conform to subject rules.
	ErrMalformedSubject = errors.New("malformed subject")

	// ErrSubscribePermissionViolation is returned when processing of a subscription fails due to permissions.
	ErrSubscribePermissionViolation = errors.New("subscribe permission violation")

	// ErrNoTransforms signals no subject transforms are available to map this subject.
	ErrNoTransforms = errors.New("no matching transforms available")

	// ErrCertNotPinned is returned when pinned certs are set and the certificate is not in it
	ErrCertNotPinned = errors.New("certificate not pinned")

	// ErrDuplicateServerName is returned when processing a server remote connection and
	// the server reports that this server name is already used in the cluster.
	ErrDuplicateServerName = errors.New("duplicate server name")

	// ErrMinimumVersionRequired is returned when a connection is not at the minimum version required.
	ErrMinimumVersionRequired = errors.New("minimum version required")
	// ErrLeafNodeMinVersionRejected is the leafnode protocol error prefix used
	// when rejecting a remote due to leafnodes.min_version.
	ErrLeafNodeMinVersionRejected = errors.New("connection rejected since minimum version required is")

	// ErrInvalidMappingDestination is used for all subject mapping destination errors
	ErrInvalidMappingDestination = errors.New("invalid mapping destination")

	// ErrInvalidMappingDestinationSubject is used to error on a bad transform destination mapping
	ErrInvalidMappingDestinationSubject = fmt.Errorf("%w: invalid transform", ErrInvalidMappingDestination)

	// ErrMappingDestinationNotUsingAllWildcards is used to error on a transform destination not using all of the token wildcards

View on GitHub (pinned to 3a66a489d2)

Solutions

Update the configured pin to the peer's current certificate
Renew or re-issue the peer certificate to match the pin
Verify pin values were copied correctly into the configuration

Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at server/errors.go:213 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

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