nats-io/nats-server · error

empty Will topic not allowed

Error message

empty Will topic not allowed

What it means

If a CONNECT packet declares a Will (Will flag set), the Will topic must be present and non-empty. When parsing the will payload, a zero-length topic returns this error (server/mqtt.go:3908); the topic is then further validated for UTF-8 and wildcard characters.

Source

Thrown at server/mqtt.go:239

	mqttRetainedCacheTTL = mqttDefaultRetainedCacheTTL
)

var (
	errMQTTNotWebsocketPort           = errors.New("MQTT clients over websocket must connect to the Websocket port, not the MQTT port")
	errMQTTTopicFilterCannotBeEmpty   = errors.New("topic filter cannot be empty")
	errMQTTMalformedVarInt            = errors.New("malformed variable int")
	errMQTTSecondConnectPacket        = errors.New("received a second CONNECT packet")
	errMQTTServerNameMustBeSet        = errors.New("mqtt requires server name to be explicitly set")
	errMQTTUserMixWithUsersNKeys      = errors.New("mqtt authentication username not compatible with presence of users/nkeys")
	errMQTTTokenMixWIthUsersNKeys     = errors.New("mqtt authentication token not compatible with presence of users/nkeys")
	errMQTTAckWaitMustBePositive      = errors.New("ack wait must be a positive value")
	errMQTTJSAPITimeoutMustBePositive = errors.New("JS API timeout must be a positive value")
	errMQTTStandaloneNeedsJetStream   = errors.New("mqtt requires JetStream to be enabled if running in standalone mode")
	errMQTTConnFlagReserved           = errors.New("connect flags reserved bit not set to 0")
	errMQTTWillAndRetainFlag          = errors.New("if Will flag is set to 0, Will Retain flag must be 0 too")
	errMQTTPasswordFlagAndNoUser      = errors.New("password flag set but username flag is not")
	errMQTTCIDEmptyNeedsCleanFlag     = errors.New("when client ID is empty, clean session flag must be set to 1")
	errMQTTEmptyWillTopic             = errors.New("empty Will topic not allowed")
	errMQTTEmptyUsername              = errors.New("empty user name not allowed")
	errMQTTTopicIsEmpty               = errors.New("topic cannot be empty")
	errMQTTPacketIdentifierIsZero     = errors.New("packet identifier cannot be 0")
	errMQTTUnsupportedCharacters      = errors.New("character not supported for MQTT topics")
	errMQTTInvalidSession             = errors.New("invalid MQTT session")
	errMQTTInvalidRetainFlags         = errors.New("invalid retained message flags")
	errMQTTInvalidRetainedMessage     = errors.New("invalid retained message")
	errMQTTSessionCollision           = errors.New("stored session does not match client ID")
	errMQTTInvalidPublishLength       = errors.New("invalid publish message, variable header exceeds remaining length")
	errMQTTAckPipelineStopped         = errors.New("QoS1 PUBACK pipeline has shut down while admitting a message, " +
		"abandoning the wait for its JetStream ack; failing the connection, " +
		"the client will re-send unacknowledged PUBLISH packets on reconnect")
)

type srvMQTT struct {
	listener     net.Listener
	listenerErr  error
	authOverride bool

View on GitHub (pinned to 3a66a489d2)

Solutions

  1. Configure the client with a valid, non-empty Will topic before connecting.
  2. If no will message is needed, clear the Will flag so no will payload is parsed.
  3. Inspect the CONNECT bytes for truncation; ensure length prefixes are correct.

Example fix

// before
opts.SetWill("", []byte("offline"), 1, false)
// after
opts.SetWill("clients/client-1/status", []byte("offline"), 1, false)
Defensive patterns

Strategy: validation

Validate before calling

// client side, when configuring a will
if willTopic == "" && willEnabled {
    return fmt.Errorf("will topic must be non-empty when the will flag is set")
}

Try / catch

// client side: on 'empty Will topic' rejection, set a valid will topic or disable the will and reconnect

Prevention

When it happens

Trigger: A CONNECT packet with mqttConnFlagWillFlag set but a zero-length Will topic string in the payload (test case: ...,0,0 after keep-alive), truncation of the packet before the topic, or a topic of only whitespace-free zero bytes.

Common situations: Hand-built CONNECT packets omitting the will topic, client library bugs where an empty will topic is passed through, or packet truncation by intermediaries.

Related errors

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