Overview
Softdrive sessions follow a defined lifecycle to establish and maintain a secure, high-performance remote connection. The process begins with Connect, where the client reaches the Softdrive backend and validates basic network access. It then moves into Handshake, during which secure TLS negotiation and session parameters are established. Once completed, the session enters Stream, where video, input, and system data flow continuously between the client and the virtual machine. Finally, Keep Alive ensures session stability by sending periodic heartbeats to detect connectivity issues and prevent stale or orphaned sessions.
The errors listed below are grouped according to the stage in which they occur. This helps quickly identify whether a failure is related to initial connectivity, security negotiation, active streaming, or session maintenance, allowing for faster troubleshooting and more accurate root-cause analysis.
Internal & HTTP Errors
| Error Code | Description | Session Phase | Typical Cause | Quick Fix |
|---|---|---|---|---|
| Error Code 1001–1004 | Internal error | Pre-Session | Unexpected client/service failure | Retry connection; restart client if persistent |
| Error Code 500 | Internal Server Error | Connect | Backend service returned an error | Retry later or contact support |
| Error Code 502 | Bad gateway | Connect | Upstream service unavailable or timed out | Retry after a few minutes |
| Error Guest Agent not Responding | Guest agent is not responding | Stream | VM agent stopped, hung, or not reporting | Restart VM; if recurring, update agent/tools |
TLS & Handshake Errors (01–06)
| Error Code | Description | Session Phase | Typical Cause | Quick Fix |
|---|---|---|---|---|
| Error Code 01 | TLSHandshakeFailed | Handshake | Firewall/TLS inspection/proxy blocking or altering TLS | Whitelist Softdrive domains; bypass SSL inspection |
| Error Code 02 | TLSHandshakeTimeout | Handshake | High latency, packet loss, or blocked outbound path | Test network stability; try alternate network |
| Error Code 03 | HandshakeTimeout | Handshake | Handshake negotiation did not complete in time | Retry connection; confirm firewall allows traffic |
| Error Code 04 | KeepAliveTimeout | Keep Alive | UDP blocked/filtered or heavy jitter causing missed heartbeats | Allow UDP; reduce filtering/EDR inspection |
| Error Code 06 | ClientException | Handshake | Local client error or dependency issue | Restart client; reinstall if it continues |
Session & Server Errors (07–11)
| Error Code | Description | Session Phase | Typical Cause | Quick Fix |
|---|---|---|---|---|
| Error Code 07 | ServerException | Stream | Server-side streaming/session process error | Retry; contact support if persistent |
| Error Code 08 | MonitorTopologyFail | Stream | Unsupported monitor layout/resolution or display change mid-connect | Reduce monitors; reset resolution; reconnect |
| Error Code 09 | SessionSettingsTimeout | Stream | Session initialization stalled (policy/agent/network delay) | Restart session; verify VM is responsive |
| Error Code 10 | OtherClientConnected | Stream | Another active session already holds the VM | Disconnect the other session; wait and retry |
| Error Code 11 | TCPConnectionFailed | Connect | Outbound TCP blocked by firewall/proxy | Allow required ports/domains; bypass proxy if needed |
Connection, Restart & Authentication Errors (12–19)
| Error Code | Description | Session Phase | Typical Cause | Quick Fix |
|---|---|---|---|---|
| Error Code 12 | TCPDisconnection | Keep Alive | Temporary network drop or unstable connection | Reconnect; stabilize Wi-Fi/VPN |
| Error Code 13 | ServerRestart | Stream | VM restarted unexpectedly or maintenance event | Wait 1–3 minutes, then reconnect |
| Error Code 14 | UserProcessTermination | Stream | User session closed, app crash, or forced logoff | Start a new session; review app stability |
| Error Code 15 | UserAuthenticationFailure | Connect | Invalid credentials, token expired, or SSO issue | Sign in again; confirm account/SSO status |
| Error Code 18 | Server is unreachable | Connect | VM offline, DNS/network blocked, or routing issue | Verify VM is powered on; check firewall/DNS |
| Error Code 19 | ConnectionFailed | Connect | General connectivity failure (often firewall/EDR/network) | Allow UDP/TCP; disable filtering; retry |
Softnet Errors.
This table maps internal or system-generated error messages to user-friendly explanations and recommended actions. It can be used for troubleshooting, support responses, and customer-facing guidance.
| Sofnet Errors. | Friendly Error Message |
|---|---|
| Reassign:internal error | This is an internal issue. Please report it. |
| Reassign:authorization error | Please sign out completely, then sign back in. |
| Reset Softstream error: failed to reset softstream: Unable to restart Softstream server process. Please restart the VM. | Please restart the machine. |
| Reassign:VM is not ready for connection: VM status is down, expected UP | Please turn on the machine. |
| Reassign:failed to run cmd: Process exited with status 1 msg: error: Guest agent is not responding: QEMU guest agent is not connected | Please restart the VM. |
| Reassign:VM is not ready for connection: missing hostname | Please restart the machine. If the issue persists, report it. |
| Reassign:failed to run cmd: Process exited with status 1 msg: error: Guest agent is not responding: Guest agent not available for now | Please restart the machine. If the issue persists, report it. |
| VM '{ID}' did not reach 'down' state after 8 attempts | Please do a force shut down. If issue persists, report it. |
| Reset Softstream error: failed to run cmd: Process exited with status 1 msg: error: Guest agent is not responding: QEMU guest agent is not connected | Softstream is unable to communicate. Please contact your internal IT support to verify that all required ports and firewall rules are properly configured. |
| VM start error: timeout of 30 seconds while starting VM {ID}, giving up (Cannot run VM because the VM is in Up status) | This is not an error. The computer you are trying to turn on is already running. |
| Reset Softstream error: failed to reset softstream: Unable to stop Softstream server process. Please restart the VM. | Please restart the machine. If the issue persists, report it. |
| Reassign:VM is not ready for connection: VM status is rebooting, expected UP | No action needed. The computer is rebooting—please wait a moment and try again. |
| Reset Softstream error: failed to run cmd: Guest agent not available for now | Please restart the machine. If the issue persists, report it. |
| Reset Softstream error: VM is not ready for connection: missing hostname | Please restart the machine. If the issue persists, report it. |
| Reset Softstream error: VM is not running | Please restart the machine. If the issue persists, report it. |
| VM creation error: Failed to start the VM after 3 tries | Please report it. |
| VM start error: timeout while starting VM {ID} (Unknown Data Center status) | Please contact your local IT administrator to inform this. |
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article