nats-io/nats-server · error

expected connect packet with protocol name %q, got %q

Error message

expected connect packet with protocol name %q, got %q

What it means

MQTT CONNECT parser (mqttParseConnect) guard: the protocol name field of the fixed header is not the expected "MQTT" string (spec MQTT-3.1.2-1). The v3.1 name "MQIsdp" is detected separately for a friendlier message; anything else lands here, so the client is likely not speaking MQTT at all.

Source

Thrown at server/mqtt.go:3800

// CONNECT protocol related functions
//
//////////////////////////////////////////////////////////////////////////////

// Parse the MQTT connect protocol
func (c *client) mqttParseConnect(r *mqttReader, hasMappings bool) (byte, *mqttConnectProto, error) {
	// Protocol name
	proto, err := r.readBytes("protocol name", false)
	if err != nil {
		return 0, nil, err
	}

	// 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
	}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Verify the client is an MQTT client connecting to the MQTT port
2. Upgrade MQTT 3.1 clients (MQIsdp) to MQTT 3.1.1/5
3. Check for TLS/plain-text port mismatches garbling the first bytes

When it happens

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