Raylux Manual

Appearance

Version 2026.20

Troubleshooting ​

Start here: is the service running, and does it answer?

powershell
sc query RayluxNexus
curl.exe http://localhost:8080/health
bash
systemctl status raylux-nexus
curl http://localhost:8080/health

Run these on the Nexus machine. Separating "Nexus is broken" from "I cannot reach Nexus" is most of the diagnosis.

The service will not start ​

Check the log first. It is in logs/ inside the data directory, and it records why.

A missing DLL, or the service stops immediately after starting ​

The Microsoft C++ runtime is not installed. This happens when the MSI was deployed on its own — the MSI cannot install the runtime, only the RayluxSetup bundle can.

Install VC_redist.x64.exe (x64), then start the service.

"Static files path not found", or Nexus runs but serves no screens ​

Nexus cannot find the web bundle. Check the service is registered with a --web-dist argument pointing at a directory that exists:

powershell
sc qc RayluxNexus

A service's working directory is C:\Windows\System32, so a relative path resolves to nowhere useful. The installer sets an absolute one; a hand-registered service may not have.

The script engine will not start ​

The bundled Python component was not installed, or RAYLUX_PYTHON_HOME points somewhere wrong. Re-run setup and select Bundled Python 3.14t runtime, or set the variable to a directory containing a free-threaded 3.14t interpreter.

It refuses to start on the configuration ​

If the log says the configuration was written by a newer version, this Nexus is older than the file. Install the matching version, or restore the backup you took before upgrading.

I cannot reach Nexus from another machine ​

Work outwards:

  1. On Nexus: curl http://localhost:8080/health. If this fails, the problem is Nexus — see above.
  2. From the other machine: Test-NetConnection nexus -Port 8080. If the port is closed, it is the network.
  3. Firewall. The installer creates rules for the Private and Domain profiles only. A machine whose network is classified Public is blocked. Check with Get-NetConnectionProfile, and either reclassify the network or add a rule deliberately.
  4. bindAddress. If it was set to 127.0.0.1, Nexus only answers locally, by design.

The browser warns about the certificate ​

Expected on a new install — it generates a self-signed certificate on first start. The connection is encrypted; what the browser objects to is that nobody vouches for the identity.

Install a real certificate, or use http:// on 8080 while commissioning on a trusted network.

It shows "Raylux Nexus is starting" and stays there ​

Nexus is still starting. First boot is slower than later ones. If it persists for more than a couple of minutes, read the log — start-up is blocked on something, and it will say what.

A device shows as disconnected ​

Open the device list in Nexus's configuration section. Each device shows its state, and the reason for a failure is in the tooltip on that state.

Common causes:

  • Wrong address, or a backplane path that does not match the physical layout.
  • A firewall between Nexus and PLC.
  • For OPC-UA: Nexus's certificate has not been trusted on the server. Raylux connects with sign-and-encrypt by default, and most servers quarantine an unknown client certificate until an administrator approves it. Look in the server's rejected-certificates list.

Tags read "Stale" or "Uncertain" ​

Stale means Nexus has not had a fresh reading in the time it expects, so the device or its connection is the place to look — not the tag.

Uncertain after an operator write means the write was sent but the read-back did not confirm it.

If a tag reads Stale while the device is plainly connected and healthy, note what the tag's scan class is: a value that genuinely never changes is normal, and Nexus accounts for that. Report it if the numbers do not add up.

The Downloads page says "Not configured" ​

The Client installers for download component was not installed. Re-run setup, choose Custom, and select it.

Reports come out in the wrong font ​

The Reporting fonts component was not installed, so PDFs fall back to a generic font. Re-run setup and select it.

I have lost the administrator password ​

There is no recovery path in the product. The user records are in the data directory on the server, and restoring them requires editing that file directly or restoring from a backup taken when you knew the password.

This is why the hardening checklist asks you to create a second administrator account.

Collecting information for a support request ​

Include:

  • Nexus version, from ConfigHub's top bar (signed in — it does not show to an anonymous visitor) or raylux-nexus --version.
  • The operating system and version.
  • The relevant section of logs/raylux_nexus.log — the lines around the failure, not just the last line.
  • What changed immediately before it started.
  • Whether /health and /health/ready answer on Nexus itself.