Troubleshooting
Start here when something is not working — a device is offline, a session will not connect, a screen is black, or a call has no video.
- troubleshooting
- support
- diagnostics
Find the symptom. Each page walks the diagnosis in the order the causes actually occur, most common first.
Device is offline or stale
— It was there, and now it is not — or it says “stale”.
Cannot connect, or the session is slow
— Sessions fail, or they work but feel sluggish.
Black screen
— It connects, and you see nothing, or only wallpaper.
Calls have no video
— Everyone joins, nobody appears.
Install problems
— It will not install, or it never appears afterwards.
Collecting diagnostics
— What to gather before asking for help.
The two commands worth trying first
roomler status # this machine: version, organization, connection, mesh address
roomler peers # every peer, and how each one is currently reachedBetween them they answer most questions before you have finished reading the symptom page.
Three things that mislead people
A device can be "connected" with no mesh at all
Being connected to the control plane and having a private network address are
separate facts. roomler status prints both on one line for exactly that
reason.
An empty list is not always "nothing there"
Where a list could mean “none” or “not configured”, the product tries to say which — an organization with the mesh off is named rather than omitted, and an empty SSH activity log means reporting is off, not that nothing happened.
A service manager can report a healthy machine as inactive
On Linux, a daemon that is running perfectly can be one systemd does not own —
systemctl is-active then says inactive while the device is online and
answering. Check pgrep -x roomlerd and roomler peers before believing it,
and do not “restart to fix” on that basis.
Still stuck?
Gather diagnostics and open an
issue at
github.com/gjovanov/roomler-ai/issues.
Include what you expected, what happened, and the output of roomler status.
In this section
Device is offline or stale
A machine that was there and is not — what online, stale and offline actually mean, and the causes in the order they usually occur.
Cannot connect, or the session is slow
Diagnose a session that will not start or feels sluggish — starting with the single most common cause, a VPN client that captured the local network.
Black screen or wallpaper only
The session connects and shows nothing — almost always a capture permission or a display-session problem, and almost never a network one.
Calls have no video
Everyone joins the call and nobody appears — the media path, why signalling can look perfect while no packets flow, and what to check first.
Install problems
The installer fails, antivirus blocks it, or the machine never appears afterwards — per-OS causes and the fixes that actually work.
Collecting diagnostics
What to gather before asking for help — status, peers, logs and a paired diagnostic bundle — and what to redact before you share it.