MiravoTroubleshooting
Fix the common first-run problems: ports in use, admin password, LAN access, missing protocols, detached start failures, stale state, and Modbus errors.
Find your symptom and apply the fix. Most problems are a port, a bind address or saved state.
Port already in use
Symptom: startup fails with a message such as Embedded MQTT broker failed to start because port 1883 is already in use. The same happens for 4840, 1502 and 8080.
Another process owns the port, often an earlier Miravo or a local Mosquitto. Find it, or pick a free port.
lsof -i :1883On Windows, run netstat -ano | findstr :1883.
miravo start --mqtt-port 1884 --opcua-port 4841 --modbus-port 1503 --admin-port 8081If the earlier Miravo is detached, run miravo stop first.
Admin password
The Console and admin API start with admin / admin. The first Console login asks for a new password and stores it in ~/.miravo/auth.json.
Set MIRAVO_ADMIN_PASSWORD to override the stored password. CLI commands such as miravo status use it too. If a command reports that the default admin credentials were rejected, export the password you chose in the Console:
export MIRAVO_ADMIN_PASSWORD='your-password'To skip the login on a local run, start with --no-auth.
Reach Miravo from another machine
Every listener binds to 127.0.0.1 by default, so a client on another machine, including Litmus Edge, cannot connect. Bind the protocol to a reachable address:
miravo start --opcua-host 0.0.0.0 --modbus-host 0.0.0.0 --mqtt-host 0.0.0.0Add --admin-host 0.0.0.0 for the Console and admin API. The Docker image already binds to 0.0.0.0.
Security
OPC UA runs with security mode None, Modbus TCP has no authentication, and the embedded MQTT broker has no authentication or TLS. Expose them only on an isolated network, and change the admin password first. See Security.
OPC UA or Modbus is not running
Built-in templates enable MQTT, OPC UA and Modbus TCP. A custom template enables only the protocols it declares under protocols:. Turn the others on from the command line:
miravo start --opcua --modbusMQTT is on unless you pass --no-mqtt. The startup summary lists the endpoints that are running. On a running factory, miravo adapter enable opcua starts one without a restart.
OPC UA fails with "standard nodeset not found"
The OPC UA server needs the nodesets/ folder that ships next to the miravo binary. It is missing when the binary was copied out of its archive. Reinstall Miravo, or keep nodesets/ beside the executable. Without OPC UA, the rest of the factory still runs.
miravo start -d fails
Detached mode hides the process output. When startup fails, Miravo prints the last 20 lines of the log and its path. The full log is ~/.miravo/detached.log, or under $MIRAVO_HOME if you set it.
Run the same command without -d to see the error live. Port conflicts and template errors are the usual causes.
--speed is rejected
--speed takes a number above 0 and up to 1000. 1 is real time and 10 is ten times faster. Change it on a running factory with miravo speed <multiplier>.
The factory starts with old assets
Miravo restores the last saved snapshot from ~/.miravo/state/. Every saved template reloads, and an unchanged one restores its saved state, so edits to a template's assets or parameters can look ignored. A changed template file loads fresh and start prints a Saved state discarded for template line.
To start fresh once:
miravo start -t smart-factory --freshTo empty the running factory and save it empty instead:
miravo reset --yesSee Persistence.
Modbus returns an exception
| Code | Name | Typical cause |
|---|---|---|
01 | Illegal Function | The function code is not 03, 04, 06, or 16. Coils and discrete inputs are not supported. |
02 | Illegal Data Address | The read goes past the register map, or a write targets a read-only, padding, or half-covered register. Check addresses with miravo adapter inspect modbus. |
03 | Illegal Data Value | Quantity out of range (1 to 125 reads, 1 to 123 writes), or the engine rejected the value: NaN, infinity, or outside the member eu_range. |
04 | Server Device Failure | Internal adapter error. Report it with the output of miravo logs. |
A float that reads as nonsense means your client uses the wrong word order. Miravo sends 32-bit values big-endian (AB CD). See Modbus TCP.
MQTT topics remain after you stop
Miravo publishes retained messages. With the embedded broker they disappear when it stops. With an external broker (--mqtt-mode external) they stay until you clear them or remove the assets. Clear a topic by publishing an empty retained message to it. To stop publishing retained values, set protocols.mqtt.retain: false in your template.
Still stuck
CLI reference
Every start flag and its default.
Security
Bind addresses and what each endpoint leaves unprotected.
Environment variables
Ports, hosts, and MIRAVO_HOME.
Was this page useful?
Last updated on