Skip to main content

Troubleshooting

Start with the logs — almost every problem shows up here:

sudo systemctl status omnibus
sudo journalctl -u omnibus -f

Installation​

"systemd not found"​

The installer provisions a systemd service. On a host without systemd, run OmniBus directly instead:

npm run build && cd dist && npm install --omit=dev && sudo PORT=80 node server.js

"Node.js is too old / not installed"​

Install Node 18+. On Debian/Ubuntu the installer offers to do this for you; otherwise:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash - && sudo apt-get install -y nodejs

npm install fails building a native module​

OmniBus's serialport dependency needs a prebuilt binary or a compiler. On x86-64 / ARM64 a prebuild is used. On other architectures, install a toolchain and re-run:

# Debian/Ubuntu
sudo apt-get install -y build-essential python3
# RHEL/Fedora
sudo dnf groupinstall -y "Development Tools" && sudo dnf install -y python3

Reaching the UI​

<hostname>.local doesn't resolve​

mDNS may be unavailable on your network or client. Use the IP address instead (hostname -I on the box). If another mDNS responder owns the host, OmniBus defers to it by design.

Browser shows a certificate warning​

Expected on first HTTPS connection with the internal CA. Either proceed past it, or install the Root CA once — download it from http://<host>/api/system/ca-cert (no login needed). See TLS.

Can't bind to port 80​

Binding low ports needs privilege. The systemd unit runs as root, so this only bites a manual node server.js run. Use sudo, grant the capability (setcap 'cap_net_bind_service=+ep' "$(readlink -f "$(which node)")"), or use a high port (PORT=8080).

Serial / bus​

A port won't open / "permission denied"​

The omnibus user must be in the dialout group (the installer adds it). Confirm the device exists (ls -l /dev/ttyUSB*) and isn't held by another process.

Garbage data or no decode​

Almost always a serial-parameter mismatch — verify baud, data bits, parity, and stop bits against the device. For RS-485, confirm A/B polarity and termination. Use a sniffer/snoop mode where the protocol offers one to see raw frames.

Nothing on a single-master bus / the bus stops working​

Don't put a second master on a single-master bus. For Metasys N2 use sniffer mode unless you're certain no other supervisor is present; for BACnet MS/TP, use sniffer to listen passively. For pool buses, leave control paths in dry-run until you've observed real traffic.

MQTT​

Tags don't appear / primitive strings vanish in Ignition​

OmniBus publishes JSON, which is the compatible choice. If a broker-side parser expects bare strings it may behave oddly — see MQTT → Payloads are JSON.

No data on topics​

Confirm the broker URL/credentials on the MQTT page, that the port has the MQTT output enabled, and that you're subscribed to the right prefix (default omnibus/<sanitized-port-path>).

Service health​

The service keeps restarting​

Restart=always plus a watchdog means a crashing or hanging process is restarted. Read journalctl -u omnibus from the start of the boot to find the underlying error (bad config, a port that can't open, a bind conflict).

Recover a lost admin password​

Use the offline lib/resetAdmin.js tool on the host, or the USB-stick factory reset.

Still stuck?​

Email support@harnessautomation.com with the output of sudo journalctl -u omnibus -n 200 and GET /api/system.