nats-io/nats-server · error

mqttConnAckRCIdentifierRejected

mqttConnAckRCIdentifierRejected

Error message

invalid character in %s %q

What it means

Raised by mqttValidateString when the MQTT client ID (or similar string field) contains characters that are not allowed in an MQTT UTF-8 string (spec MQTT-1.5.3 control/non-character restrictions). The CONNACK identifier-rejected return code accompanies it for client IDs.

Source

Thrown at server/mqtt.go:3891

	// Client ID
	c.mqtt.cid, err = r.readString("client ID")
	if err != nil {
		return 0, nil, err
	}
	// Spec [MQTT-3.1.3-7]
	if c.mqtt.cid == _EMPTY_ {
		if cp.flags&mqttConnFlagCleanSession == 0 {
			return mqttConnAckRCIdentifierRejected, nil, errMQTTCIDEmptyNeedsCleanFlag
		}
		// Spec [MQTT-3.1.3-6]
		c.mqtt.cid = nuid.Next()
	}
	// Spec [MQTT-3.1.3-4] and [MQTT-3.1.3-9]
	if err := mqttValidateString(c.mqtt.cid, "client ID"); err != nil {
		return mqttConnAckRCIdentifierRejected, nil, err
	} else if !isValidName(c.mqtt.cid) {
		// Should not contain characters that make it an invalid name for NATS subjects, etc.
		err = fmt.Errorf("invalid character in %s %q", "client ID", c.mqtt.cid)
		return mqttConnAckRCIdentifierRejected, nil, err
	}

	if hasWill {
		cp.will = &mqttWill{
			qos:    wqos,
			retain: wretain,
		}
		var topic []byte
		// Need to make a copy since we need to hold to this topic after the
		// parsing of this protocol.
		topic, err = r.readBytes("Will topic", true)
		if err != nil {
			return 0, nil, err
		}
		if len(topic) == 0 {
			return 0, nil, errMQTTEmptyWillTopic
		}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Change the client ID to use only valid MQTT UTF-8 characters (no U+0000 or non-characters)
2. Let the server generate an ID by sending an empty client ID with the clean-session flag

When it happens

Trigger: Thrown at server/mqtt.go:3891 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/e16f36421c785672. Report an issue: GitHub.