nats-io/nats-server · error

mqttConnAckRCUnacceptableProtocolVersion

mqttConnAckRCUnacceptableProtocolVersion

Error message

unacceptable protocol version of %v

What it means

MQTT CONNECT parser guard on the protocol level byte (spec MQTT-3.1.2-2): it differs from the supported mqttProtoLevel. The returned return-code (mqttConnAckRCUnacceptableProtocolVersion) is sent back to the client in the CONNACK before the connection is dropped.

Source

Thrown at server/mqtt.go:3810

	}

	// Spec [MQTT-3.1.2-1]
	if !bytes.Equal(proto, mqttProtoName) {
		// Check proto name against v3.1 to report better error
		if bytes.Equal(proto, mqttOldProtoName) {
			return 0, nil, fmt.Errorf("older protocol %q not supported", proto)
		}
		return 0, nil, fmt.Errorf("expected connect packet with protocol name %q, got %q", mqttProtoName, proto)
	}

	// Protocol level
	level, err := r.readByte("protocol level")
	if err != nil {
		return 0, nil, err
	}
	// Spec [MQTT-3.1.2-2]
	if level != mqttProtoLevel {
		return mqttConnAckRCUnacceptableProtocolVersion, nil, fmt.Errorf("unacceptable protocol version of %v", level)
	}

	cp := &mqttConnectProto{}
	// 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]

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Set the client's MQTT protocol level to a version supported by the server
2. Upgrade the client library to an MQTT version compatible with the broker

When it happens

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