nats-io/nats-server · error

message headers not supported

Error message

message headers not supported

What it means

The parser received an HPUB (headers-enabled publish) but the connection never declared header support — c.headers is false in processHeaderPub because headers:true was absent from the client's CONNECT. The at-fault input is the client's CONNECT options, not the message itself.

Source

Thrown at server/errors.go:185

	// ErrNoSysAccount is returned when an attempt to publish or subscribe is made
	// when there is no internal system account defined.
	ErrNoSysAccount = errors.New("system account not setup")

	// ErrRevocation is returned when a credential has been revoked.
	ErrRevocation = errors.New("credentials have been revoked")

	// ErrServerNotRunning is used to signal an error that a server is not running.
	ErrServerNotRunning = errors.New("server is not running")

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

	// ErrBadMsgHeader signals the parser detected a bad message header
	ErrBadMsgHeader = errors.New("bad message header detected")

	// ErrMsgHeadersNotSupported signals the parser detected a message header
	// but they are not supported on this server.
	ErrMsgHeadersNotSupported = errors.New("message headers not supported")

	// 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.

View on GitHub (pinned to 3a66a489d2)

Solutions

  1. Enable headers on the connection (headers: true in CONNECT / client options)
  2. Use plain PUB instead of HPUB if headers are not needed
  3. Upgrade to a client library that supports NATS headers
Defensive patterns

Strategy: validation

When it happens

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

Common situations: See trigger scenarios.

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