SSL_ERROR_WANT_READ is returned by OpenSSL when a non-blocking SSL operation cannot complete because the TLS library needs to read more data from the underlying socket before it can proceed. This is not an error in the traditional sense — it is a signal used in non-blocking I/O programming that tells the application to wait for the socket to become readable and then retry the SSL operation. However, if an application does not properly handle this return code (by retrying the operation after the socket is ready), it can manifest as stalled connections, timeouts, or apparent hangs. This is one of the most commonly mishandled return codes in OpenSSL programming.
The application is using OpenSSL in non-blocking mode but does not properly wait for the socket to be readable before retrying the SSL operation. It may be interpreting WANT_READ as a fatal error instead of a retry signal.
During a TLS renegotiation (which can be initiated by either side), an SSL_write() call may return WANT_READ because the renegotiation requires reading the peer's handshake messages before the write can proceed. This catches many application developers off guard.
On high-latency or congested networks, TLS records may arrive in fragments. OpenSSL returns WANT_READ to signal that it has received a partial record and needs the rest before it can process it.
Review the application's OpenSSL integration code. When SSL_read(), SSL_write(), or SSL_do_handshake() returns an error, call SSL_get_error() and handle SSL_ERROR_WANT_READ by waiting for the socket to become readable (using select/poll/epoll) and retrying the same SSL call.
Use openssl s_client to verify the server is responding correctly. If the connection works fine with s_client, the issue is in the application's non-blocking I/O handling.
openssl s_client -connect yourdomain.com:443 -servername yourdomain.com
If the application does not require non-blocking I/O, switch to blocking mode where OpenSSL handles the read/write retries internally. This eliminates the need to handle WANT_READ manually.
If the issue is intermittent, network problems may be causing incomplete TLS records. Check the connection quality between client and server.
Scan PortsAn I/O error occurred during an SSL operation, typically indicating a network-level problem or abrupt connection termination.
An error occurred in the SSL/TLS library itself, typically indicating a protocol violation or internal processing failure.
The TLS connection was shut down cleanly by the peer sending a close_notify alert.