DOCUMENTATION

The remote desktop session does not connect

An RDP, SSH, VNC or isolated-browser session will not start — or it starts, but paste and file transfer do nothing inside it.

Symptom

The vendor is signed in and allowed; the session page opens and then stays on a connecting state, shows an engine error, or disconnects at once. Web-app resources on the same connector work. In a second family of reports the session itself is fine, but Ctrl+V does nothing in a terminal or a dragged file never arrives.

Check these first

  1. Under Infrastructure → Resources, check the health column of the remote-desktop resource. Unreachable means the connector host cannot even open the port; nothing else matters until that is green.
  2. Open the connector's page and read Gateway logs (guacd) or, for an isolated browser, Isolated browser logs. The engine states the reason for a failed handshake in plain words.
  3. On the connector host, confirm the engines are running: docker ps must list captivo-guacd and captivo-kasm next to access-connector.

Possible causes

The target is unreachable from the connector

How to tell: The resource shows Unreachable, and the gateway log reports a connection refused or a timeout to the target host and port.

Fix: The connector host must reach the target on the protocol port: 3389 for RDP, 22 for SSH, 5900 for VNC, or whatever you entered. Test from that host, for example nc -vz 10.0.5.30 3389. Fix the host firewall on the target, a network ACL between the two, or a wrong address on the resource. If every resource is unreachable at once, the connector itself may be down (see connector shows offline).

Wrong credential or RDP security mode

How to tell: The resource is Reachable, the session starts and drops within seconds. The gateway log shows an authentication failure, or for RDP a security negotiation error.

Fix: The username and secret are stored in the vault on the resource and injected server-side; the vendor never types them, so a typo there fails for everyone. Re-enter them under Infrastructure → Resources. For RDP, also match the security mode to the server: try NLA first, then TLS, then plain RDP, and remember that a domain account needs its domain field. Details in adding a remote desktop.

The session engine (guacd / KasmVNC) is not running

How to tell: Web apps on the connector work, every remote-desktop session fails immediately, and docker ps is missing captivo-guacd (or captivo-kasm for isolated browsers). Or the connector log shows a denied dial to captivo-guacd:4822.

Fix: The console's install command starts both engines next to the connector on a shared Docker network; a hand-written command or a removed container leaves them out. Run the full command again, or docker start captivo-guacd / docker start captivo-kasm. If you set ALLOWED_TARGETS on the connector, it must also include captivo-guacd:4822, captivo-kasm:6901 and captivo-kasm:7900, otherwise the connector refuses to dial its own engines (see egress boundary).

Paste appears not to work

How to tell: The session is fine, but Ctrl+V in an SSH terminal prints nothing or a stray ^V. In RDP or VNC, paste sometimes works and sometimes does not.

Fix: In an SSH terminal the engine pastes on Ctrl+Shift+V or a right or middle click; plain Ctrl+V is delivered to the shell as the ^V character, which is expected. RDP and VNC paste with Ctrl+V. The session's control panel shows the clipboard status; if it says a direction is blocked, that is the resource's or the policy's clipboard setting doing so on purpose (see per-resource settings).

A dropped file goes nowhere

How to tell: The vendor drags a file onto the session; the drop is accepted or shows a blocked overlay, and the file never appears on the remote side.

Fix: File transfer is off by default. Turn File transfer: On on the resource, or set it as the remote-desktop default under Infrastructure → Policy; a resource left on Default inherits that policy value. SSH transfers go over SFTP and land in the login user's home unless an SFTP upload folder is set; RDP presents a mapped drive; an isolated browser has separate upload and download switches. Every transfer is written to the audit log (see clipboard, file transfer and watermark defaults).

Recording consent is pending

How to tell: The session page shows a recording notice with an accept button and does not connect until it is pressed; if the vendor declines, the session ends.

Fix: This is Require recording consent under Infrastructure → Policy, not a fault: the vendor must accept that the session is recorded before it starts. Tell the vendor to accept, or switch the gate off if your compliance stance does not need it (see recording mode, consent and retention).

Keys a browser cannot send — F-keys, arrows, Ctrl+Alt+Del — are on the session's on-screen keyboard in the control panel. A key that seems ignored is usually one the browser kept for itself.

If it is still not solved

  • Protocol (RDP, SSH, VNC, isolated browser) and the target's port
  • The resource's health as shown in the console
  • The last lines of Gateway logs or Isolated browser logs around the attempt
  • The output of docker ps on the connector host
  • Whether ALLOWED_TARGETS or an egress policy is set on that connector

Was this article helpful?