Complete troubleshooting
Complete EMQX troubleshooting: the symptom, the check and the safe fix for an add-on that will not start, a client that cannot connect, a Dashboard you cannot open, port conflicts, running out of resources and authentication failures.
Why this matters
When EMQX misbehaves, the hard part is rarely that something is broken. It is not knowing where to start looking. Plenty of people see the add-on fail to start, remove and reinstall the whole thing, and end up wiping their settings and losing their accounts too. The right order is: read the log, check the ports, then check resources — most problems come from one of those three.
By the end of this chapter you will have four symptom → check → safe fix checklists: will not start, cannot connect, Dashboard will not open, and resources or ports eaten up. You will also be able to tell a configuration mistake from a limit of the environment, instead of guessing.
Core concepts
Start by fixing the order in which you diagnose. The Woow add-on README and the EMQX docs agree on the same first move: start with the log. The log tells you the real reason a start failed, instead of leaving you watching a spinner.
Read the log
The add-on log shows the startup sequence, the ngrok status and EMQX errors. Most start failures have their reason right here.
Check the ports
If another add-on is holding 1883 or 18083, EMQX cannot listen. Check first whether Mosquitto, WebRTC and the like are still running.
Check resources
EMQX uses more than Mosquitto does. Too little memory makes the add-on restart over and over, or not start at all.
Every repair step should be the smallest safe action: do not delete data on a hunch, and do not quietly move a port out onto the open network. Before you touch data at all, take a backup.
Terms at a glance
| Term | Plain English | In one line |
|---|---|---|
| Symptom | what you notice | The odd behavior you can actually see |
| Diagnosis | finding the cause | The process of tracking down the root cause |
| Safe Fix | a low-risk change | A small adjustment that deletes no data |
| Log | the add-on's log | Where the add-on records startup and errors |
| Port Conflict | two services, one port | Two services want the same port |
| Resource Limit | not enough RAM or CPU | Too little RAM/CPU squeezes the add-on |
Set a diagnostic baseline
Confirm the add-on really started
Open the Woow EMQX page in Home Assistant and see whether the state is started or a restart loop. A restart loop usually shows a port or memory reason in the log.
Check 1883 and 18083
Make sure no Mosquitto or WebRTC is holding 1883/8083, so EMQX does not exit at startup because its listener port is taken.
Search the log for keywords
Search the add-on log for "address already in use", "cannot bind" or "out of memory" and you narrow the problem down fast.
Test with an MQTT client you trust
Connect to 1883 with a small tool you already have (the WebSocket client, or your HA MQTT). If it connects, the broker is accepting connections; if it does not, check whether authentication is set up and whether the port and address are right.
Will not start, and running out of resources
Symptom: the add-on drops back to stopped shortly after it starts, or hangs on starting.
- Check: read the log first; then confirm whether another service is holding the port (Mosquitto uses 1883, WebRTC uses 8083), and confirm the host still has enough memory.
- Safe fix: stop the conflicting add-on or shed some load, then start EMQX once more. If memory is short, turn off the other add-ons that eat resources. Leave the data directory alone.
EMQX needs more RAM/CPU than Mosquitto does; the Woow README recommends at least 512MB RAM. If your host also runs video or AI services, cut back there before you add anything here.
Cannot connect, and authentication failures
Symptom: HA, Z2M or an outside device drops when it connects to 1883, or the error says authentication failed.
- Check: confirm Authentication is configured in EMQX; confirm the username and password you are using exist in the built-in database and are correct; confirm the broker address (homeassistant, 1883) is right.
- Safe fix: if authentication is not set up, create a user first; if an account was changed by mistake, create it again and switch to the correct password. Never print a real password into a log or into an answer.
One thing to watch: while EMQX has no authentication configured, it lets every client connect — that is not proof the connection is working properly. Either set up authentication, or turn anonymous access off.
Dashboard will not open / port conflicts
Symptom: clicking Open Web UI gives you no page, or 18083 will not open.
- Check: whether another service is holding 18083; whether the add-on is in the started state; whether Ingress is actually reachable.
- Safe fix: go in through the EMQX icon in the Home Assistant sidebar (Ingress); stop or adjust whatever service conflicts with 18083; restart the add-on and try again.
The Dashboard is the way in to the whole broker. If you want to reach 18083 directly, make sure it is not exposed to the public internet.
Quick fix reference
- Symptom: the add-on will not start and the log shows a port already in use → stop Mosquitto or WebRTC first; confirm 1883/8083 are free, then start it.
- Symptom: cannot connect, and authentication keeps failing → confirm Authentication is set up, the credentials are correct and the broker address and port are right; stop using the default public.
- Symptom: the Dashboard will not open → go in through Ingress; if you hit 18083 directly, confirm there is no port conflict and that it is not exposed straight to the public internet.
- Symptom: connections drop after a while → check the resource limits and Rate Limit; EMQX uses more resources than Mosquitto, and a host tight on memory will make it less stable.
- Symptom: ngrok is enabled but there is no public URL → see Chapter 19: check the authtoken, restart, and read the ngrok service log.
FAQ
Is reinstalling the add-on faster than fixing it?
Often it is not. Note the difference: upgrading the add-on does not clear your data, while reinstalling — especially removing it and installing it again — can take the data with it. Read the log first to rule out something you could fix in a minute, then consider a reinstall; and if you do go ahead, back up /data/emqx first.
How do I find out what is holding 1883?
Usually it is Mosquitto (1883) or the WebRTC integration (8083). Check the add-on and integration lists in Home Assistant and pause whichever one conflicts.
How do I tell that memory is the problem?
Look in the add-on log for messages such as "out of memory" or "not enough system RAM". At least 512MB is recommended. With the resource-hungry add-ons paused, EMQX settles down more easily.
Nothing outside can connect: is that EMQX or my network?
Test the local connection first, with a client on the same network. If the local network works and the outside does not, go back to the router/ngrok or the firewall. If even the local attempt fails, it is usually the authentication or the listener port settings.