Troubleshooting
The gateway does not start
Section titled “The gateway does not start”Another program holds port 5100. CONNECT refuses to start on a taken port instead of silently moving to another one, because the port is part of what every client addresses. Free the port, or run this instance on another one with the environment variable REALVIRTUAL_CONNECT_PORT and point its clients there.
A second CONNECT is already running. Check the tray — a gateway that is already up owns the port.
Windows blocked the file. SmartScreen may hold the first start of a freshly downloaded executable. The build is signed by realvirtual GmbH; the confirmation is behind More info.
The browser shows nothing
Section titled “The browser shows nothing”Check the address. http://localhost:5100 on the gateway PC, http://<host>:5100 from another machine.
From another machine, check the key. With an API key configured, a remote browser has to be introduced once with http://<host>:5100/?apikey=<key>. Without that step it gets a 401 for everything, including the page itself. See remote access.
Check the firewall. A Windows firewall rule for port 5100 is needed for access from other machines.
An interface will not connect
Section titled “An interface will not connect”Read the reason on the interface card first — it names the failing step. The usual causes per protocol:
| Protocol | Check |
|---|---|
| S7 | PUT/GET communication enabled on the CPU; optimized block access disabled for the addressed data blocks |
| PLCSIM Advanced | Network adapter switched from Softbus to PLCSIM Virtual Eth. Adapter |
| TwinCAT | An AMS route on the PLC pointing back to the gateway PC and its Net Id |
| OPC UA | Endpoint reachable, and the security policy accepted by the server |
| MQTT | Broker URL and port, credentials, and whether the topic actually publishes |
| EtherNet/IP | Path — 1,0 for a backplane, and no path at all for Micro800 |
| Festo | Only one Festo interface per gateway is possible |
| ctrlX (bridge mode) | The bridge snap installed and running on the device |
| ABB RobotStudio, shared memory | Gateway and the other program on the same PC |
A failing interface retries by itself with a growing backoff of up to 30 seconds. There is no need to restart the gateway after fixing the cause.
Connected, but no values arrive
Section titled “Connected, but no values arrive”Check the direction. A signal the PLC is supposed to supply must be PLCOutput; a signal realvirtual supplies must be PLCInput. A wrong direction produces no error — the value simply never moves. See configuring interfaces.
Check the address. The interface card shows an amber badge for signals whose address could not be parsed or that point outside the received data.
Check the signal count against your license. Signals beyond the licensed limit are listed by name rather than silently dropped. See licensing.
Values arrive, but the model does not move
Section titled “Values arrive, but the model does not move”Names must match. The viewer binds signals to model components by name; the CONNECT panel marks bound and unbound signals. A typo shows up there.
Commands need write access. Writing from the HMI to the controller requires Allow web to PLC on that interface. It is off by default.
Only some signals update
Section titled “Only some signals update”For an MQTT process image, an out of bounds badge means the payload is shorter than the tag table expects — usually a tag table from a different PLC program version. It clears by itself once a matching payload arrives.
CAD import fails
Section titled “CAD import fails”Over the limit — the message names whether the license limit or this gateway’s configured capacity applied. See CAD conversion.
Unreadable JT — a shattered JT, whose parts live in separate files, is not reliably detected. Export a monolithic file.
No “via CONNECT” option — the gateway reports whether it can convert at all, and the viewer offers only what is available. An older gateway build may not have the feature.
Diagnosis answers nothing useful
Section titled “Diagnosis answers nothing useful”No documents — the documentation folder is empty; the answer says so explicitly.
No model key — the feature reports that it is not configured rather than guessing.
Too many requests — requests are rate-limited per minute so a flapping error signal cannot trigger a storm.
Use Test AI Query… in the tray menu to check the pipeline without going through the HMI. See AI diagnosis.
Nothing here matches
Section titled “Nothing here matches”GET /health on the gateway answers without any authentication and reports version, build and capability flags. It is the fastest way to tell “the gateway is not running” from “the gateway is running but refusing me”.