Skip to main content

Troubleshooting handshake errors in OpenShift

Have you ever received a TLSHandshake error when connecting to OpenShift? Here are some ways to resolve it.
Troubleshooting handshake errors

Photo by Pixabay from Pexels

If you work in a restricted network environment, you may encounter some problems when using the Red Hat Openshift command line to connect to a Red Hat cluster. One possible issue is a TLSHandshake error when you use the oc login command. This problem can occur with Kubernetes, as well. This blog discusses a few possible causes for the error, and how you can resolve it. 

My example applies to Red Hat OpenShift, but these tips also work when managing OKD, which is the upstream community version of Red Hat OpenShift.

The problem usually falls into one of two categories:

  • Proxy settings
  • Certificate corrupted/incorrect

Let's look at these categories in the following sections.

Check proxy settings

The first step is to check the proxy settings. If you cannot disable the proxy configuration, you can set no_proxy. Do this just for your OpenShift cluster URL by using the process below.

For a temporary fix/check, execute the following command in your terminal window: 

#> export no_proxy=OC_CLUSTER_URL

Where OC_CLUSTER_URL is the destination OpenShift cluster web site address.

For a permanent solution, add the following line to your ~/.bashrc  or ~/.bash_profile files:

export no_proxy=OC_CLUSTER_URL

Check for a corrupted certificate

If the issue is not with the proxy, the problem is likely with a certificate. Start by logging in to the OpenShift web console URL. Next, select your user name in the top right corner, and then select the Copy Login option. Log in using that credential instead of the default command. For example:


Additional suggestions

If configuring the proxy or updating the certificate did not work, here are some additional troubleshooting steps to try:

1. Increase the log level output on OpenShift authentication to gather more information. Run the following command:

#> oc login OPENSHIFT_CLUSTER_URL --loglevel=9

2. Run oc version to check the OpenShift version.

3. Run oc config view to display the current certificate.

I will discuss the certificate information next.

Display the certificate

You can follow the steps below to generate the current certificate by using a TLS/SSL certificate management tool like OpenSSL. There are other certificate management tools available, as well.

1. Run the following command:


Where OPENSHIFT_CLUSTER_URL is the OpenShift cluster. Use the following format: and OPENSHIFT_CLUSTER_PORT is the port exposed through OpenShift.

2. Once the certificate is generated, you can pass the parameter:

#> oc login: --certificate-authority=extracted-certificate-file-path

Where extracted-certificate-path is the path to the downloaded certificate (e.g. ./downloaded.cert).

Wrap up

In this article, I examined some of the common causes of TLSHandshake errors when accessing an OpenShift cluster through the OpenShift command line. I also demonstrated some ways resolve it. As you continue on your OpenShift system administrator journey, it will be useful to be aware of the different challenges that you may encounter. Be sure to check out other articles in this blog site to continue to improve your system administrator skills.

[ Start using containers for free with OpenShift. ]

Topics:   OpenShift   Kubernetes  
Author’s photo

Bryant Son

Bryant Jimin Son is a Consultant at Red Hat, a technology company known for its Linux server and opensource contributions. More about me

Try Red Hat Enterprise Linux

Download it at no charge from the Red Hat Developer program.