nats-io/nats-server · error

wildcards not allowed in publish's topic: %q

Error message

wildcards not allowed in publish's topic: %q

What it means

MQTT topic validation for PUBLISH (specs MQTT-3.3.2-2 and MQTT-4.7.1-1): the topic being published contains wildcard characters (+ or #), which are only permitted in subscriptions, never in publishes.

Source

Thrown at server/mqtt.go:6251

			// nodes) where the resulting control line could be split.
			return nil, errMQTTUnsupportedCharacters
		case 0x7f:
			// SubjectTree uses DEL as an internal pivot marker, so retained
			// subjects containing it cannot be indexed safely, including
			// legacy retained messages recovered from the retained-message
			// stream.
			return nil, errMQTTUnsupportedCharacters
		case btsep:
			if !cp {
				makeCopy(i)
			}
			res = append(res, mqttTopicLevelSep, mqttTopicLevelSep)
			j++
		case mqttSingleLevelWC, mqttMultiLevelWC:
			if !wcOk {
				// Spec [MQTT-3.3.2-2] and [MQTT-4.7.1-1]
				// The wildcard characters can be used in Topic Filters, but MUST NOT be used within a Topic Name
				return nil, fmt.Errorf("wildcards not allowed in publish's topic: %q", mt)
			}
			if !cp {
				makeCopy(i)
			}
			if mt[i] == mqttSingleLevelWC {
				res = append(res, pwc)
			} else {
				res = append(res, fwc)
			}
		default:
			if cp {
				res = append(res, mt[i])
			}
		}
		j++
	}
	if cp && res[j-1] == btsep {
		res = append(res, mqttTopicLevelSep)

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Publish to a concrete topic without + or #
2. Use wildcards only in SUBSCRIBE filters

When it happens

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