nats-io/nats-server · error

%ssubscribe protocol must contain at least 1 topic filter

Error message

%ssubscribe protocol must contain at least 1 topic filter

What it means

MQTT SUBSCRIBE/UNSUBSCRIBE parser guard (specs MQTT-3.8.3-3 and MQTT-3.10.3-2): the payload contained no topic filters, but at least one is mandatory. The 'action' verb (un)subscribe is prefixed into the message.

Source

Thrown at server/mqtt.go:5347

		if err != nil {
			c.Errorf("invalid topic %q: %v", topic, err)
		}
		if sub {
			qos, err = r.readByte("QoS")
			if err != nil {
				return 0, nil, err
			}
			// Spec [MQTT-3-8.3-4].
			if qos > 2 {
				return 0, nil, fmt.Errorf("subscribe QoS value must be 0, 1 or 2, got %v", qos)
			}
		}
		f := &mqttFilter{ttopic: topic, filter: string(filter), qos: qos}
		filters = append(filters, f)
	}
	// Spec [MQTT-3.8.3-3], [MQTT-3.10.3-2]
	if len(filters) == 0 {
		return 0, nil, fmt.Errorf("%ssubscribe protocol must contain at least 1 topic filter", action)
	}
	return pi, filters, nil
}

func mqttSubscribeTrace(pi uint16, filters []*mqttFilter) string {
	var sep string
	sb := &strings.Builder{}
	sb.WriteString("[")
	for i, f := range filters {
		sb.WriteString(sep)
		sb.Write(f.ttopic)
		sb.WriteString(" (")
		sb.WriteString(f.filter)
		sb.WriteString(") QoS=")
		sb.WriteString(fmt.Sprintf("%v", f.qos))
		if i == 0 {
			sep = ", "
		}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Include at least one topic filter in every SUBSCRIBE/UNSUBSCRIBE packet
2. Fix the client's packet construction if filters are being dropped

When it happens

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