VNC connection issues
Blank screens, WebSocket errors, and input problems in the VNC viewer.
Blank or black screen
You opened the VNC viewer and see a black rectangle instead of your desktop.
The desktop is still booting
This is the most common cause. The VNC connection can establish before the desktop environment finishes starting. The graphical session needs the initialization process to complete and XFCE to load, which takes up to 60 seconds after the VM is created.
Wait for the dashboard to show running. If it already says running, give it another 15 to 20 seconds for the display server to initialize.
The desktop has stopped
If the desktop was running and the screen went black, the VM may have stopped or crashed.
Go back to the dashboard and check the status. If it shows stopped, start it again. If it shows running but the screen is still black, refresh the page.
Display resolution mismatch
Rarely, the VNC viewer fails to negotiate the display resolution, resulting in a black or partially rendered screen.
Refresh the browser tab. The VNC client will reconnect and renegotiate the display.
WebSocket connection failed
You see "WebSocket connection failed" or the viewer never loads.
Desktop is not running yet
The WebSocket proxy only connects to desktops that are fully booted with a confirmed IP address. If the desktop is still in pending or booting, the connection will fail.
Wait for the status to reach running before opening the viewer.
Network or firewall
If you are behind a corporate firewall, WebSocket connections may be blocked.
Test on a different network (a mobile hotspot, for example). If it works there, your firewall is blocking WebSocket traffic.
Browser compatibility
The viewer works best in modern browsers. Outdated browsers or aggressive privacy extensions can interfere with WebSocket connections.
Use a recent version of Chrome, Firefox, or Edge. Temporarily disable extensions to rule them out.
Keyboard or mouse not working
You can see the desktop but keyboard and mouse input is not registering.
Browser focus
The VNC canvas needs focus to capture input. If you clicked outside the viewer or switched tabs, input stops being forwarded.
Click directly on the VNC viewer area. If that does not help, refresh the page.
Keyboard layout mismatch
The VNC viewer sends keycodes based on your local keyboard layout. The VM uses US layout by default. If you have a different layout, some special characters may not map correctly.
Clipboard
Copy-paste between your local machine and the VNC session does not work through the VNC protocol.
Use the terminal panel for operations that need clipboard access. The terminal supports standard copy-paste.
If nothing else works
Try these in order:
- Refresh the page to force a new WebSocket connection
- Try a different browser
- Confirm the desktop is in running state
- Stop and restart the desktop to clear any stuck display state
- If the problem happens across multiple desktops, email contact@talentai.fr