If you are dealing with Node-RED MQTT not connecting, the node usually sits on a yellow "connecting" ring or flips between connected and disconnected, and the rest of your flow goes quiet. This guide gives you a fast, ordered way to find the cause: read the right logs, prove the broker is reachable outside Node-RED, then work through ports, TLS, hostnames, client IDs, credentials and container networking until the status turns green.
Know the Symptoms
The status under an mqtt in or mqtt out node is your first clue:
| Status | What it usually means |
|---|---|
| Yellow ring, "connecting" forever | Node-RED cannot complete a connection at all: wrong host or port, TLS mismatch, firewall, DNS |
| Red ring, "disconnected" | The broker refused or closed the connection; check credentials and logs |
| Green then red every few seconds | Another client is using the same client ID, or keepalive problems |
| Green, but no messages | Connection is fine; the problem is the topic, QoS or publisher |
| Grey or no status | The node is not wired to a broker configuration, or the flow is not deployed |
Note the last two. A green status means the connection works, so skip ahead to topics. Many "not connecting" reports are really subscription problems.
Step 1: Read the Node-RED Log
The editor only shows a short status. The Node-RED log has the real error. Where you find it depends on how you run Node-RED:
# Started from a terminal: the log is in that terminal
# Installed as a systemd service (e.g. Raspberry Pi script)
journalctl -u nodered -f
# Docker
docker logs -f nodered
Look for lines from the MQTT broker node such as Connection failed to broker: .... The text after the colon, for example Connection refused: Not authorized, getaddrinfo ENOTFOUND, ECONNREFUSED or a certificate error, points straight to one of the sections below.
Step 2: Test Outside Node-RED
Before changing anything in Node-RED, prove that the machine can reach the broker. The Mosquitto clients are the quickest way. Try the public MQTT test broker first, since it needs no credentials:
mosquitto_sub -h broker.connectmq.com -p 1883 -i nr-test-6b0e \
-t "connectmq/demo/6b0e/#" -v
In a second terminal:
mosquitto_pub -h broker.connectmq.com -p 1883 -i nr-test-pub-6b0e \
-t "connectmq/demo/6b0e/ping" -m "hello"
If hello appears, outbound MQTT works from this machine. Now test your private broker exactly as Node-RED will connect, with TLS and credentials:
mosquitto_sub -h YOUR_BROKER_HOST -p 8883 \
--capath /etc/ssl/certs \
-u YOUR_USERNAME -P YOUR_PASSWORD -i YOUR_CLIENT_ID \
-t "test/#" -v -d
The -d flag prints the CONNECT and CONNACK packets. If this command fails, the problem is the network, the certificate or the credentials, not Node-RED. If it succeeds and Node-RED still fails, compare the Node-RED settings field by field with this command. Stop the test client before starting Node-RED, because it is using the same client ID.
Step 3: Check Server, Port and TLS Together
Most connection loops come from a mismatch between port and TLS settings. Most brokers use these standard ports:
| Port | Transport | Node-RED broker node settings |
|---|---|---|
| 1883 | MQTT over TCP | Use TLS unticked |
| 8883 | MQTT over TLS | Use TLS ticked |
| 8083 | MQTT over WebSocket | Server ws://host:8083/mqtt |
| 8084 | MQTT over secure WebSocket | Server wss://host:8084/mqtt |
Common mistakes:
- Port 8883 without TLS. Node-RED sends plain MQTT to a TLS port; the broker waits for a TLS handshake and the node keeps reconnecting.
- Port 1883 with TLS ticked. Node-RED starts a TLS handshake against a plain port and fails.
- Scheme in the server field. Enter just the hostname, such as
broker.connectmq.com, for TCP and TLS. Only use aws://orwss://URL when you intend to connect over WebSocket. - Typos and whitespace. A trailing space in the hostname produces DNS errors that are hard to spot.
For TLS, also check that Verify server certificate is enabled and that the server name matches the certificate. ConnectMQ uses a Let's Encrypt certificate, which Node.js trusts by default, so you do not need to upload a CA file. If you added a custom TLS configuration with an old CA file, remove it. The complete setup is in Node-RED MQTT TLS.
Step 4: Rule Out Duplicate Client IDs
MQTT brokers allow only one connection per client ID. When a second client connects with the same ID, the broker disconnects the first. If both clients reconnect automatically, they kick each other off endlessly, which shows up as a status that flips between connected and disconnected.
Typical sources of duplicates:
- Two Node-RED instances, such as a laptop and a Raspberry Pi, deployed with the same flow.
- A test
mosquitto_subleft running with Node-RED's client ID. - A Docker container recreated while the old one is still running.
- Two broker configuration nodes in one Node-RED with the same ID.
Give each instance a unique ID. On the public broker any non-empty unique string works. On ConnectMQ private brokers, client IDs are bound to the issued credentials, so use the client ID shown in the portal and do not reuse that credential set on a second instance; create another credential for it instead.
Step 5: Check Credentials and Account Limits
A connection refused right after connecting usually means authentication. With MQTT 3.1.1 you will see return codes 4 or 5 (bad username or password, not authorized); with MQTT 5 you will see reason codes such as 0x86 or 0x87. Re-enter the username and password in the broker node's Security tab, then deploy. Credentials are stored separately from flows, so importing a flow on a new machine brings the broker settings but not the password.
Two less obvious causes:
- Repeated failed logins. ConnectMQ blocks an IP address after repeated failed login attempts. If you deployed a wrong password and Node-RED retried many times, fix the credentials and allow the block to clear before concluding the new password is wrong too.
- Connection quotas. Every plan has a connection limit; the free Serverless plan allows up to 25 connections. Over the limit, an MQTT 5 broker can reject with reason code
0x97(quota exceeded). Count all your devices, dashboards and Node-RED instances.
Step 6: Fix Networking, DNS and Containers
If the log shows ENOTFOUND, ETIMEDOUT or ECONNREFUSED:
- Firewalls. Corporate and some guest networks block outbound 1883 and 8883. Try secure WebSocket on 8084, which often passes where raw MQTT does not.
- Docker localhost. Inside a container,
localhostis the container. Use the broker's hostname, a Compose service name orhost.docker.internal; see Node-RED Docker. - DNS. Run
nslookup YOUR_BROKER_HOSTon the Node-RED host. Gateways with misconfigured DNS fail here first. - Proxies. Node-RED's MQTT client does not route through an HTTP proxy for raw TCP; WebSocket connections can be more proxy-friendly.
Step 7: Check Keepalive and Session Settings
If the connection drops every minute or two on an otherwise healthy network, look at keepalive. A value of 60 seconds suits most links. Very long values let NAT routers silently drop idle connections. Also make sure Clean session settings and the protocol version match what your flow expects. Mixing MQTT 5 features into a broker node set to 3.1.1 will not prevent connecting, but can explain odd behaviour after it connects.
Quick Troubleshooting Checklist
- Is the flow deployed and the MQTT node linked to a broker configuration?
- Does the Node-RED log show a specific error?
- Does
mosquitto_subconnect from the same machine with the same settings? - Do port and TLS settings match (1883 plain, 8883 TLS)?
- Is the server field a bare hostname with no typos?
- Is the client ID unique across every running client?
- Are the username and password correct, and is your IP not temporarily blocked?
- Are you under your plan's connection limit?
- Does DNS resolve and is the port open from this network or container?
If the status is green but messages do not arrive, check topics and wildcards, and see the Node-RED MQTT tutorial for a known-good flow. The official Node-RED MQTT node documentation also explains each broker setting.
Get a Broker That Is Easy to Debug
Troubleshooting is faster when you can see the broker side. ConnectMQ is a fully managed MQTT service with a portal that includes an in-browser MQTT client and a live topic explorer, so you can check whether Node-RED's messages arrive. You can also subscribe to $SYS/broker/connection/{clientId}/state to watch whether a specific client is connected. Create a free Serverless broker at app.connectmq.com, no credit card required, and copy the exact host, port, username, password and client ID into Node-RED. For background, read about choosing a cloud MQTT broker.
Frequently Asked Questions
Why is my Node-RED MQTT node stuck on connecting?
Usually the host or port is wrong, TLS does not match the port, or a firewall blocks the connection. Check the Node-RED log for the exact error and test the same settings with mosquitto_sub.
Why does my Node-RED MQTT node keep connecting and disconnecting?
The most common cause is a duplicate client ID: another client with the same ID keeps taking over the session. Give every Node-RED instance and test tool a unique client ID.
Do I need to upload a CA certificate to connect to ConnectMQ?
No. ConnectMQ uses a Let's Encrypt certificate that Node.js trusts by default. Tick Use TLS, use port 8883 and leave certificate verification on.
Can Node-RED connect to MQTT through a corporate firewall?
If ports 1883 and 8883 are blocked, try MQTT over secure WebSocket on port 8084 with the path /mqtt, which is more likely to be allowed.
