Troubleshooting

Connecting

What the app or the web viewer says when a connection fails, and what to do:

Message	Likely cause	What to do
The device is offline.	The remote PC isn't connected to the server: it is off or asleep, has no network, the service stopped, or it uses another server.	Check the remote PC's main window (its status line). The admin console's Devices page shows when it was last seen. If it is asleep, try Wake-on-LAN.
No device has that ID on this server.	A typing mistake, the PC uses a different server, or the device was deleted (it then registered under a new ID).	Check the ID on the remote PC, and that both PCs use the same server.
This server asks you to sign in before you connect.	The server only lets signed-in users connect.	Sign in (top right in the app, at the bottom of the web viewer's page).
The connection was refused (by the remote user, or the server does not allow it).	The person at the PC clicked Deny; or you are signed in but the device isn't yours or your group's; or your address isn't on the PC's allowed list.	Ask the person; ask your administrator to give you access to the device (owner or group), or to check the allowed networks.
That device is disabled on the server.	An administrator disabled it.	Ask your administrator.
The device is busy - it refused the connection.	Too many people are connected to, or signing in to, that PC at once.	Wait a minute and try again.
No answer in time (from the device or the remote user).	Nobody clicked Accept within 60 seconds, the whole sign-in took longer than 150 seconds, or the PC didn't answer the server within 10 seconds.	Try again; for Accept, make sure someone is at the PC.
Too many connection attempts - wait a minute and try again.	More than 20 connection attempts a minute from your address, or 30 to that device.	Wait a minute.
Connections from your country are blocked by this server.	The server's administrator blocks the country your internet address belongs to (connecting and signing in).	Ask the administrator; a VPN that puts you in another country is not the answer if your organization chose the block.
Waiting for the person at the remote PC to confirm...	You used the one-time password of a PC you haven't connected to before: the person there sees a scam warning and must click Accept (it waits 10 seconds).	Ask them to click Accept. If they click Deny, the connection is refused.
Wrong password.	A wrong or old one-time password: it changes after every session that used it.	Read the current one on the remote PC.
Too many wrong passwords - wait a minute and try again.	6 wrong passwords in a minute from your address, or 30 in 10 minutes from anywhere.	Wait. If you didn't make those attempts, someone may be guessing: tell your administrator.
The device does not allow this kind of connection.	The PC must have two-factor sign-in by policy but none is set up; or it only accepts passwords and has none; or it doesn't allow this kind of session.	Set up two-factor sign-in or a password on that PC, or use another kind of session.
Wrong two-factor code.	A wrong code, or the clock on the PC or the phone is off. Each code works only once.	Wait for the next code; check both clocks.
Device key changed	Obsidian Remote was reinstalled on that PC, or someone is between you and it.	Compare the key with the one in that PC's Settings > About before clicking Connect anyway.
The device's key could not be trusted.	The PC presented a different key than the server vouches for.	The device may have been reinstalled or reset: ask your administrator to check it on the Devices page.
The device closed the connection - direct IP access may be off there.	You connected by address and the PC doesn't allow direct IP access.	Turn on Allow direct IP access without the server on that PC, or connect by ID.
No server is set up - add one in Settings > Network, or connect by IP address.	No server is set up in this app.	Add your server in Settings > Network (see Getting started).

Sessions always use the relay on the same network

The remote PC has Accept direct connections from the local network off, Windows Firewall blocks TCP 21118 (the installer's rule covers private and domain networks only, not public ones, and only viewers on the remote PC's own subnet), or the two PCs are on different networks. See Local network and Wake-on-LAN.

This PC's status line

What the main window says about this PC's connection to the server:

Status	Cause	What to do
No server set - reachable on the LAN only	No server is set up.	Add it in Settings > Network, or ask IT.
The server refused this PC: id_key_mismatch	The PC has a new key for an ID the server ties to the old one: its data was deleted, or it is a copy of another PC's disk.	Your administrator uses Release ID (or Delete) for the device; see Devices, users, groups and address books. A PC cloned from another needs its own ID: IT removes the copied ID and key from the clone's `%ProgramData%\ObsidianRemote`.
The server refused this PC: disabled	An administrator disabled the device.	Ask your administrator.
Not connected to the server, with a certificate error	The server's certificate changed, and this PC still checks for the old key.	Paste the new client config string into Settings > Network (your administrator has it in Server settings).
Not connected to the server, otherwise	The name doesn't resolve, a firewall or proxy is in the way, or the server is down. HTTPS inspection also breaks the key check.	Open `https://remote.example.com:21114/healthz` (your server's address) in a browser on the PC: it should say `ok`. See Ports and firewalls.

During a session

Problem	Cause	What to do
The picture is black at the sign-in screen, the lock screen or administrator prompts	The remote PC runs the portable version, which can't see those screens.	Install the MSI on that PC.
Ctrl+Alt+Del needs the installed service.	The remote PC runs the portable version.	Install the MSI on that PC.
Low frame rate, the remote PC works hard	That PC has no hardware video encoder (some virtual machines, old graphics cards), so it encodes in software.	Picture quality > Fastest response, or a lower custom frame rate.
The status line says the video is decoded in software	Your PC's graphics driver offers no hardware video decoding.	Update your graphics driver. It works anyway, with more processor load.
No sound	Play the remote sound is off, the remote PC doesn't allow sound, nothing is playing there; in the web viewer, the browser can't play it or waits for a click on the page.	Check the option and the permission; click inside the page.
The Windows key and Alt+Tab work on my PC, not the remote one	The session window isn't in front, the session is view-only, or (web viewer) you aren't in full screen.	Click the picture; in the web viewer go full screen in Chrome or Edge.
The wrong characters appear	The two PCs have different keyboard layouts.	View options > Keyboard: characters (this PC's layout).
No user is logged on and file transfer or tunnels refused	Nobody is signed in at the remote PC.	Sign in on the remote PC through the session first.
The terminal could not start	Your PC lacks the WebView2 runtime (Windows 10).	Install the Evergreen WebView2 runtime from Microsoft.
Privacy mode is not available on this host.	The remote PC runs a Windows version older than Windows 10 2004.	Use Block the remote user's input instead.
The session ends after some minutes without input	The remote PC disconnects idle sessions (its setting or a policy).	Change the setting or the policy, if appropriate.
A tunnel drops after 2 minutes of no traffic	The server closes relayed sessions without traffic after 2 minutes.	Normal sessions are not affected; your administrator can raise `relayIdleSeconds`.
The web viewer says This browser cannot show remote screens (it lacks WebCodecs).	Firefox or an old browser.	Use a current Chrome, Edge or Safari. File transfer still works.

The server

Problem	Cause	What to do
The service doesn't start, the log says the config file is not found	The service points at a missing `server.json`.	Run the installer again, or create `/etc/obsidian-remote/server.json`.
`/setup` says the token is wrong	A user already exists (the token only works while there are none), or the token is old.	`sudo cat /var/lib/obsidian-remote/setup-token`; if users exist, sign in normally.
A user can't sign in to the console	5 failures in 15 minutes from that address, or 20 in an hour for that user.	Wait for the block to pass. If the password was forgotten, another administrator can set a new one on the Users page. With no other administrator, set one on the server (see the next row).
An administrator lost their two-factor phone		Another administrator: Users > Reset two-factor. If there is only one administrator, do it on the server: in the server menu, Console users, or `sudo obsidian-remote-console reset-2fa NAME`. A forgotten password: `sudo obsidian-remote-console set-password NAME`. (A server installed from the tarball: `sudo -u obsidian-remote /opt/obsidian-remote/ObsidianRemote.Server admin reset-2fa NAME --config /etc/obsidian-remote/server.json`.) The audit log records it as "command line".
PCs stopped connecting after a certificate change	The server's own certificate was replaced (data folder lost, or `cert.pem` replaced), so its key changed.	Restore `cert.pem` and `key.pem` from the backup, or give every PC the new client config string.

Log files

If you ask for help, you may be asked for the log files. They record what happened (connections, errors), never passwords, keys or sign-in tokens.

Part	Where
The Windows app	`%LocalAppData%\ObsidianRemote\viewer\logs`, or Settings > About > Open the log folder
This PC, installed	`%ProgramData%\ObsidianRemote\logs` (administrators only)
This PC, portable	`%LocalAppData%\ObsidianRemote\logs`
The server	`journalctl -u obsidian-remote` on the server
The web viewer	the browser's developer console (F12)

Checking a PC's video

On a PC where the picture is slow or doesn't appear, an administrator can test screen capture and video encoding without any network, in a command prompt in the program folder:

ObsidianRemote.Host.exe --probe

It lists the displays and the video encoders (hardware first), records the screen for 5 seconds and prints the frame rate, size and encoder used. The file it writes is a recording of that screen, so delete it afterwards.

Two environment variables force the software path, to rule out a graphics driver problem: OBSIDIAN_REMOTE_DECODER=software for the app's video decoding, and OBSIDIAN_REMOTE_ENCODER=software for the remote PC's encoding.