nats-io/nats-server · error

malformed subject

Error message

malformed subject

What it means

Subscription-time validation: the subject in a SUB fails subject-syntax rules (misplaced wildcards such as '>' not last, empty tokens, or illegal characters). The server sends -ERR 'Invalid Subject' to the client and returns this sentinel from processSub.

Source

Thrown at server/errors.go:204

	// ErrNoRespondersRequiresHeaders signals that a client needs to have headers
	// on if they want no responders behavior.
	ErrNoRespondersRequiresHeaders = errors.New("no responders requires headers support")

	// ErrClusterNameConfigConflict signals that the options for cluster name in cluster and gateway are in conflict.
	ErrClusterNameConfigConflict = errors.New("cluster name conflicts between cluster and gateway definitions")

	// ErrClusterNameRemoteConflict signals that a remote server has a different cluster name.
	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.

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Place '>' only as the final token and '*' within tokens
2. Remove empty tokens (a..b) and illegal characters
3. Validate subjects client-side before subscribing

When it happens

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

Common situations: See trigger scenarios.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

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