nats-io/nats-server · error

QoS=%v is invalid in MQTT

Error message

QoS=%v is invalid in MQTT

What it means

MQTT PUBLISH parser guard: the QoS bits extracted from the fixed-header flags evaluate to 3, which is a reserved/invalid value in MQTT (only 0, 1, 2 exist). The packet is malformed and the connection is failed.

Source

Thrown at server/mqtt.go:4248

	}
	if will.retain {
		pp.flags |= mqttPubFlagRetain
	}
	c.mu.Unlock()
	s.mqttInitiateMsgDelivery(c, pp)
	c.flushClients(0)
}

//////////////////////////////////////////////////////////////////////////////
//
// PUBLISH protocol related functions
//
//////////////////////////////////////////////////////////////////////////////

func (c *client) mqttParsePub(r *mqttReader, pl int, pp *mqttPublish, hasMappings bool) error {
	qos := mqttGetQoS(pp.flags)
	if qos > 2 {
		return fmt.Errorf("QoS=%v is invalid in MQTT", qos)
	}

	if c.mqtt.rejectQoS2Pub && qos == 2 {
		return fmt.Errorf("QoS=2 is disabled for PUBLISH messages")
	}

	// Keep track of where we are when starting to read the variable header
	start := r.pos

	var err error
	pp.topic, err = r.readBytes("topic", false)
	if err != nil {
		return err
	}
	if len(pp.topic) == 0 {
		return errMQTTTopicIsEmpty
	}
	if err := mqttValidateTopic(pp.topic, "topic"); err != nil {

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Fix the publisher's fixed-header flags encoding
2. Use a spec-compliant MQTT client library

When it happens

Trigger: Thrown at server/mqtt.go:4248 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/698620dd171fb85b. Report an issue: GitHub.