# Replace STOMP with KubeMQ (/deploy/scenarios/replace/replace-stomp)



<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>

Point your existing STOMP client at KubeMQ by changing the broker host — the connection
changes, your STOMP client library and destination code don't.

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

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

The STOMP connector is disabled by default. Start KubeMQ with it turned on:

<RunKubeMQ env="{ CONNECTORS_STOMP_ENABLE: 'true' }" ports="[61613, 61614, 50000]" />

<Callout type="warn">
  The enable variable is `CONNECTORS_STOMP_ENABLE` — with the underscore between
  `CONNECTORS` and `STOMP`. `CONNECTORSSTOMP_ENABLE` (no underscore) is silently ignored.
</Callout>

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

Change the broker host to KubeMQ's plain-TCP port. Everything else — the client
library, `SEND`/`SUBSCRIBE` calls, destination names — stays the same.

Before:

```python
import stomp

conn = stomp.Connection([("stomp-host", 61613)])
conn.connect("user", "password", wait=True)
```

After (KubeMQ):

```python
import stomp

conn = stomp.Connection([("localhost", 61613)])
conn.connect("user", "password", wait=True)   # any login/passcode when auth is disabled
```

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

In one terminal, subscribe to a queue destination:

```python
# consumer.py
import stomp, time

class Listener(stomp.ConnectionListener):
    def __init__(self, conn):
        self._conn = conn

    def on_message(self, frame):
        print("RECEIVED:", frame.body)
        self._conn.ack(frame.headers["ack"])

conn = stomp.Connection([("localhost", 61613)])
conn.set_listener("", Listener(conn))
conn.connect(wait=True)
conn.subscribe(destination="/queue/smoke-test", id="s1", ack="client-individual")

time.sleep(10)
conn.disconnect()
```

In a second terminal, publish one message:

```python
# producer.py
import stomp

conn = stomp.Connection([("localhost", 61613)])
conn.connect(wait=True)
conn.send(destination="/queue/smoke-test", body="hello from stomp")
conn.disconnect()
print("sent")
```

Expected output in the consumer terminal:

```text
RECEIVED: hello from stomp
```

(from the [full verification smoke
test](/connectors/stomp/scenarios/migration-from-stomp#verification-smoke-test))

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

Your STOMP client library, connection API, and all five destination types (`/queue`,
`/topic`, `/topic-store`, `/command`, `/query`) carry over unchanged. STOMP transactions
and message selectors don't — both are rejected outright.

<Cards>
  <Card title="STOMP getting started" href="/connectors/stomp/tutorials/getting-started" description="The full connect → send → subscribe walkthrough." />

  <Card title="Migrating from STOMP" href="/connectors/stomp/scenarios/migration-from-stomp" description="The complete compatibility matrix and deviations." />
</Cards>

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

<Callout type="warn">
  * **Wrong port** — plain TCP is `61613`; TLS is `61614`. Confirm your client dials the
    one you enabled.
  * **Connector not enabled** — a stock server doesn't bind the STOMP listener until
    `CONNECTORS_STOMP_ENABLE=true` is set (verbatim, with the underscore). Check `docker
    logs kubemq` for a bind error.
  * **Auth mismatch** — if `Authentication.Enable = true` on the server, the CONNECT
    `passcode` must carry a valid KubeMQ JWT; with auth disabled, any value works.
</Callout>