nats-io/nats-server · error

if Will flag is set to 0, Will QoS must be 0 too, got %v

Error message

if Will flag is set to 0, Will QoS must be 0 too, got %v

What it means

MQTT CONNECT flags validation (spec MQTT-3.1.2-13): the Will Flag bit is 0 but the Will QoS bits are non-zero, an illegal combination. The parser extracts wqos from the connect-flags byte and rejects the packet before any session work happens.

Source

Thrown at server/mqtt.go:3832

	// Connect flags
	cp.flags, err = r.readByte("flags")
	if err != nil {
		return 0, nil, err
	}

	// Spec [MQTT-3.1.2-3]
	if cp.flags&mqttConnFlagReserved != 0 {
		return 0, nil, errMQTTConnFlagReserved
	}

	var hasWill bool
	wqos := (cp.flags & mqttConnFlagWillQoS) >> 3
	wretain := cp.flags&mqttConnFlagWillRetain != 0
	// Spec [MQTT-3.1.2-11]
	if cp.flags&mqttConnFlagWillFlag == 0 {
		// Spec [MQTT-3.1.2-13]
		if wqos != 0 {
			return 0, nil, fmt.Errorf("if Will flag is set to 0, Will QoS must be 0 too, got %v", wqos)
		}
		// Spec [MQTT-3.1.2-15]
		if wretain {
			return 0, nil, errMQTTWillAndRetainFlag
		}
	} else {
		// Spec [MQTT-3.1.2-14]
		if wqos == 3 {
			return 0, nil, fmt.Errorf("if Will flag is set to 1, Will QoS can be 0, 1 or 2, got %v", wqos)
		}
		hasWill = true
	}

	if c.mqtt.rejectQoS2Pub && hasWill && wqos == 2 {
		return mqttConnAckRCQoS2WillRejected, nil, fmt.Errorf("server does not accept QoS2 for Will messages")
	}

	// Spec [MQTT-3.1.2-19]

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Fix the client's CONNECT flags: set Will QoS to 0 when no Will message is used
2. Use a compliant MQTT client library that encodes the connect flags correctly

When it happens

Trigger: Thrown at server/mqtt.go:3832 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/60171e17e2a9b05c. Report an issue: GitHub.