rdp-cli

Troubleshoot RDP connections, black screens and blocked input

Applies to: 0.1.2 · Windows / macOS / Linux · RDP

Start with the actual response

Work through RDP connection problems in order: network, encryption, authentication, screen and input. Use the returned error code to choose the next step instead of repeatedly changing passwords or reconnecting.

rdp-cli --version
rdp-cli list
rdp-cli status --session SESSION

Replace SESSION with your own returned session ID. Read error.code, error.message and error.retryable on failure. In a successful status response, inspect data.connection_state, data.control_state, data.last_error when present, and data.capabilities. A retryable flag does not authorize replaying input.

Check the connection layer

Error What to check and do
CONNECT_TIMEOUT / RDP_CONNECT_FAILED Verify the host, configured port (normally 3389), LAN/VPN route and a running RDP service. Have the administrator check the listener and permitted firewall rule. A reachable port alone does not prove a successful RDP login. Retry once after correcting the cause.
RDP_TLS_HANDSHAKE_FAILED Check the server TLS configuration. The default modern profile requires TLS 1.2. Use --tls-profile legacy only for an identified legacy target on a trusted network; it permits older cryptography. Do not apply it to every connection or disable server security to make a test pass.
CERTIFICATE_UNTRUSTED Under --cert-policy strict, verify the server name and certificate chain, or verify the reported SHA-256 fingerprint with the administrator before adding an exact trust record. The current default is ignore; that does not verify server identity. Do not switch to ignore just to silence a strict-mode failure.
AUTH_FAILED Check the username, local/domain account choice, --domain and remote-logon permission. Use the password prompt or an existing credential reference from quick start. Do not cycle passwords: TLS failure and an unreachable host are not evidence of a bad password.

A connected session has no usable picture

Run the following read-only query and open the PNG at data.path. connected means activation and a coherent frame were received; the frame may still be a login, Welcome or black screen. It does not prove that the desktop is ready.

rdp-cli screenshot --session SESSION

If FRAME_UNAVAILABLE is returned, inspect status and error.retryable, then capture again after reconnection or a display change settles. If the screen stays black, check the server, client sleep state and VPN connection. Inspect the current screen before entering credentials.

Resolve input and permission errors

  • OBSERVATION_REQUIRED: capture and read a fresh image; use its data.observation for the next action. Refresh after reconnect, takeover or display changes.
  • SESSION_PAUSED, CONTROL_HELD_BY_HUMAN or CONTROL_NOT_OWNED: stop input and respect the current controller. Resume only after an authorized handoff, then capture again; do not bypass the pause with another viewer.
  • PERMISSION_DENIED / CAPABILITY_UNAVAILABLE: inspect the relevant capability and access grant. A viewer cannot enable an unsupported server feature. UNICODE_INPUT_UNAVAILABLE requires a supported input method, not blind retries.

Recover an uncertain action

Before input that may need recovery, specify and save a unique --request-id for each distinct action; replace the example request IDs with your own values. If error JSON arrives, retain its top-level request_id; if the response is completely lost and no original ID was saved, do not invent a new ID to query the old action or blindly resend it.

After REQUEST_TIMEOUT or SERVICE_UNAVAILABLE during an action, retain its original request ID. Check the local service with list and query the original operation before deciding to retry. The call may have sent input even when its response was lost.

rdp-cli operations status --session SESSION --request-id REQUEST_ID
rdp-cli status --session SESSION
rdp-cli screenshot --session SESSION

Replace REQUEST_ID with the original value, not the ID of the status query. Inspect data.state, retained data.result and a fresh screenshot. OPERATION_NOT_FOUND can mean the record expired or the service changed; it does not prove the action never ran. After correcting a connection problem, an explicit reconnect of a non-closed session remains paused. SESSION_CLOSED needs a new authorized connection; do not attempt to revive it by repeatedly reconnecting.

Enhanced commands in rdp-cli

Run rdp-cli --version first. The commands below require agent_execution.contract_version to be 1; older builds can continue using the single-step workflow above.

Replace uppercase placeholders with actual returned values. In Windows PowerShell, use .\rdp-cli.exe from its folder; on macOS or Linux, use the installed command or the executable’s actual path.

Connect your agent and find connection problems

Use the executable’s built-in MCP interface or CLI. Save named connection profiles with credential references and use doctor to inspect the available connection layers.

This doctor example reads existing evidence; it does not request an active probe. Unknown or not-run is not a passed check. Connection profiles store credential references rather than passwords in the examples.

rdp-cli profiles list
rdp-cli doctor --session SESSION

Continue with the right evidence

If unresolved, report the client version, server version, protocol, time, error code and redacted status/screenshot. Remove passwords, access tokens and private screen content.

Download · Quick start · Command reference