nats-io/nats-server · error

if Will flag is set to 1, Will QoS can be 0, 1 or 2, got %v

Error message

if Will flag is set to 1, Will QoS can be 0, 1 or 2, got %v

What it means

MQTT CONNECT flags validation (spec MQTT-3.1.2-14): the Will Flag is set but the Will QoS value is 3, which is reserved/invalid (only 0, 1 or 2 are allowed for a Will message).

Source

Thrown at server/mqtt.go:3841

	}

	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]
	hasUser := cp.flags&mqttConnFlagUsernameFlag != 0
	// Spec [MQTT-3.1.2-21]
	hasPassword := cp.flags&mqttConnFlagPasswordFlag != 0
	// Spec [MQTT-3.1.2-22]
	if !hasUser && hasPassword {
		return 0, nil, errMQTTPasswordFlagAndNoUser
	}

	// Keep alive

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Set the Will message QoS to 0, 1 or 2
2. Regenerate the CONNECT packet with a spec-compliant flags byte

When it happens

Trigger: Thrown at server/mqtt.go:3841 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/826cd10669590d04. Report an issue: GitHub.