Client ID

Every MQTT connection carries a client identifier (client ID) — the string a client puts in its CONNECT packet to tell the broker who it is. For a conceptual introduction — what a client ID is and how a take-over looks on the wire — see the MQTT Client ID guide. This page covers how TBMQ handles client IDs: uniqueness, client take-over, broker-assigned IDs, and length limits.

TBMQ allows only one active connection per client ID, and it enforces this across the whole cluster — not merely per node. When a second CONNECT arrives with a client ID that already has a live session, TBMQ performs a client take-over: it keeps the new connection and disconnects the previous one, even when the two clients are connected to different broker nodes.

An MQTT 5.0 client that is displaced receives a DISCONNECT with reason code SESSION_TAKEN_OVER (0x8E), so it can tell a take-over apart from other drops. This is a normal part of session management — a device that reboots and reconnects transparently resumes its session — but a steady stream of take-overs on one ID almost always means two clients were accidentally given the same identifier.

Whether a take-over fires the displaced client’s Last Will depends on its will delay; see Last Will and Keep alive for that interaction.

TBMQ uses the client ID as the key for a client’s persistent-session state — its subscriptions and any queued messages. A client that wants to resume its session after reconnecting must present the same client ID it used before; that is what lets TBMQ locate the stored state and restore it. A persistent session therefore requires a stable client ID — see Non-persistent and persistent sessions.

A client may send an empty client ID and let the broker assign one. TBMQ generates a unique identifier for such a connection and, for MQTT 5.0 clients, returns it in the CONNACK as the Assigned Client Identifier property, so the client learns the ID it was given.

A generated ID only makes sense for a clean (non-persistent) session — there is no stable key to map stored state back to on the next connect. TBMQ therefore refuses a CONNECT that sends no client ID while asking to resume a session (MQTT 3.1.1 Clean Session = 0, or MQTT 5.0 Clean Start = 0). The connection is rejected with Client identifier not valid (0x85) for MQTT 5.0 clients, or Identifier rejected (0x02) for MQTT 3.x clients.

MQTT version	Client ID rules in TBMQ
MQTT 3.1	Length is capped at 1024 characters, set by the MQTT_3_1_MAX_CLIENT_ID_LENGTH environment variable.
MQTT 3.1.1 / 5.0	Follows the MQTT specification — a server must accept 1–23 UTF-8 characters from 0-9, a-z, A-Z; longer IDs and a wider character set are permitted, and TBMQ accepts them without an additional length cap.

• Use a stable, unique ID per device or application instance whenever you rely on persistent sessions — that stability is what lets a client resume its state across reconnects.
• Derive the ID from something inherently unique, such as a serial number or MAC address, so two units can never collide.
• Never share one ID across devices. Because TBMQ keeps only the newest connection per ID, duplicated IDs make clients repeatedly take each other over in a reconnect loop.