{"record":{"id":"6d3f53d29018e17d","repo":"nats-io/nats-server","slug":"subscribe-qos-value-must-be-0-1-or-2-got-v","errorCode":null,"errorMessage":"subscribe QoS value must be 0, 1 or 2, got %v","messagePattern":"subscribe QoS value must be 0, 1 or 2, got (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/mqtt.go","lineNumber":5339,"sourceCode":"\t\t\treturn 0, nil, err\n\t\t}\n\t\tvar qos byte\n\t\t// We are going to report if we had an error during the conversion,\n\t\t// but we don't fail the parsing. When processing the sub, we will\n\t\t// have an error then, and the processing of subs code will send\n\t\t// the proper mqttSubAckFailure flag for this given subscription.\n\t\tfilter, err := mqttFilterToNATSSubject(topic)\n\t\tif err != nil {\n\t\t\tc.Errorf(\"invalid topic %q: %v\", topic, err)\n\t\t}\n\t\tif sub {\n\t\t\tqos, err = r.readByte(\"QoS\")\n\t\t\tif err != nil {\n\t\t\t\treturn 0, nil, err\n\t\t\t}\n\t\t\t// Spec [MQTT-3-8.3-4].\n\t\t\tif qos > 2 {\n\t\t\t\treturn 0, nil, fmt.Errorf(\"subscribe QoS value must be 0, 1 or 2, got %v\", qos)\n\t\t\t}\n\t\t}\n\t\tf := &mqttFilter{ttopic: topic, filter: string(filter), qos: qos}\n\t\tfilters = append(filters, f)\n\t}\n\t// Spec [MQTT-3.8.3-3], [MQTT-3.10.3-2]\n\tif len(filters) == 0 {\n\t\treturn 0, nil, fmt.Errorf(\"%ssubscribe protocol must contain at least 1 topic filter\", action)\n\t}\n\treturn pi, filters, nil\n}\n\nfunc mqttSubscribeTrace(pi uint16, filters []*mqttFilter) string {\n\tvar sep string\n\tsb := &strings.Builder{}\n\tsb.WriteString(\"[\")\n\tfor i, f := range filters {\n\t\tsb.WriteString(sep)","sourceCodeStart":5321,"sourceCodeEnd":5357,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/mqtt.go#L5321-L5357","documentation":"MQTT SUBSCRIBE parser guard (spec MQTT-3.8.3-4): the requested QoS byte for a topic filter is greater than 2, which is reserved and invalid. Parsing aborts before the subscriptions are registered.","triggerScenarios":"Thrown at server/mqtt.go:5339 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Request QoS 0, 1 or 2 for each topic filter","Fix the SUBSCRIBE packet encoding in the client"],"exampleFix":null,"handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}