# Replace MQTT with KubeMQ (/deploy/scenarios/replace/replace-mqtt)



<Callout type="info">
  You need a license key to start KubeMQ — it's free, about 2-3 minutes (it includes creating a free account). 

  [Get one](/deploy/license-key)

  . Step 1 below starts the broker with the connector enabled.
</Callout>

Your existing MQTT client keeps its library, its code, and its publish/subscribe
calls — only the **broker host** changes. MQTT 3.1.1 and 5.0 clients both connect
unchanged (MQTT 3.1 is rejected at CONNECT).

**Drop-in level:** endpoint-only ([legend](/deploy/scenarios/replace#drop-in-levels))

## 1 · Enable the connector [#1--enable-the-connector]

The MQTT connector is disabled by default — enable it and publish its ports:

<RunKubeMQ env="{ CONNECTORSMQTT_ENABLE: 'true' }" ports="[1883, 8883, 8083, 50000]" />

<Callout type="warn">
  **The enable variable is `CONNECTORSMQTT_ENABLE`** — no underscore between
  `CONNECTORS` and `MQTT`. `CONNECTORS_MQTT_ENABLE` is silently ignored.
</Callout>

## 2 · Point your client at KubeMQ [#2--point-your-client-at-kubemq]

```bash title="Before — existing MQTT broker"
mqtt://broker.example.com:1883
mqtts://broker.example.com:8883
```

```bash title="After — KubeMQ"
mqtt://localhost:1883
mqtts://localhost:8883
```

Only the host:port changes. Topics keep working as-is if they don't start with a
reserved prefix (`events/`, `store/`, `queues/`, `commands/`, `queries/`) — those
prefixes select a KubeMQ messaging pattern; everything else routes through the
default pattern.

## 3 · Smoke test [#3--smoke-test]

Adapted from the MQTT connector's
[verification smoke test](/connectors/mqtt/scenarios/migration#verification-smoke-test):

```bash title="Terminal 1 — subscribe"
mosquitto_sub -h localhost -p 1883 -t 'events/smoke/test'
```

```bash title="Terminal 2 — publish"
mosquitto_pub -h localhost -p 1883 -t 'events/smoke/test' -m '{"ok":true}'
```

You should see, in Terminal 1:

```text
{"ok":true}
```

## What carries over — and what doesn't [#what-carries-over--and-what-doesnt]

Your MQTT library, connection code, and publish/subscribe calls carry over
unchanged for both 3.1.1 and 5.0. Retained messages are rejected (not silently
dropped), MQTT 3.1 is rejected at CONNECT, and RPC over MQTT only works on 5.0 —
see the full deviations list below.

<Cards>
  <Card title="MQTT connector getting started" href="/connectors/mqtt/tutorials/getting-started" description="The full publish-and-subscribe walkthrough across every language client." />

  <Card title="Migrating from MQTT" href="/connectors/mqtt/scenarios/migration" description="The full cutover guide — topic-prefix mapping, compatibility matrix, and deviations." />
</Cards>

## Didn't work? [#didnt-work]

<Callout type="warn">
  * **Connector not enabled** — the MQTT connector is opt-in; confirm
    `CONNECTORSMQTT_ENABLE=true` (exact spelling, no underscore before `MQTT`) was set
    when the container started.
  * **CONNACK rejected the connection** — check your client isn't sending MQTT 3.1
    (protocol level 3); use 3.1.1 or 5.0.
  * **Message never arrives** — subscribe before you publish (Events is
    fire-and-forget), and check your topic's first segment isn't unintentionally
    colliding with a reserved prefix (`events/`, `store/`, `queues/`, `commands/`,
    `queries/`).
</Callout>