Skip to main content

The VNC console cannot be opened

Symptom​

The virtual machine console does not open in the web interface, and the connection is not established.

How to check​

Follow these steps in order: each step is relevant only if the previous check passes.

  1. Machine state. The console opens only for a running machine: check the State column in the VM list. A stopped machine has no console button.
  2. Permissions. The Access VM Console privilege (1102) allows opening the console. Without it, the call returns -403.
  3. Security log. In the Security Event Log section, set the Category filter to virtual machines. A successful connection records vm.console_connected, a failed connection records vm.console_connect_failed, and the console request itself records vm.console_access. These show whether the request reached the WSS bridge or failed earlier. The first two event types were introduced in 3.0.5.
  4. Network path to the HTTPS endpoint. The WebSocket connection must pass through the entire path: proxies and load balancers that do not pass Upgrade break the console connection, while regular API calls continue to work.

Cause​

The console works through the WebSocket proxy on the cluster's HTTPS endpoint. Unavailability is usually caused by an expired session or a blocked WebSocket connection on the path to the HTTPS endpoint.

There is also a third, less obvious cause: the "console token–machine" mapping is held in dispatcher memory for 300 seconds, which is also the default lifetime of the WSS bridge. The mapping is deliberately not persistent. This has two consequences. A console link cannot be opened later: after five minutes, it is no longer associated with anything. Restarting the dispatcher loses the mapping. Open consoles continue to work because the cluster's HTTPS endpoint maintains the bridge. Log enrichment is lost: the connection event is recorded without the user or machine, leaving only the token fingerprint and client address in the record.

Failures of the console call itself have separate codes: -3103 means no machine exists with that ID or it is outside your visibility scope; -3112 means an unsupported console type was requested; -403 means the privilege is missing; -78 means a database error.

Resolution​

Refresh the session (sign in again) and verify that the network path to the cluster's HTTPS endpoint allows WebSocket connections, then reopen the console.

If the log shows vm.console_connect_failed, the request reached the bridge, and the problem is the network or the mapping's lifetime: reopen the console from the interface rather than from a saved link. If the log contains none of the three events, the failure occurred before the bridge: check the machine state and the privilege.

API methods​

The API operations covered on this page are vm-console, vm-get, and security-event-list. See the API reference.

See also​