Katalon Studio can’t log in behind a proxy even with the right settings

[nghi.phan]

If your team works behind a corporate proxy, you may have entered the proxy address and port, checked them twice, and Katalon Studio still won’t connect. This guide is for that situation. Setting the proxy is only half the job. The other half is certificate trust, and most teams miss it.

Is this you?

• Katalon Studio or Katalon Runtime Engine (KRE) runs on a machine with no direct internet access, so all traffic goes through a corporate HTTP/HTTPS proxy.
• You entered the correct proxy address and port under Manual proxy configuration, and Studio still can’t connect, log in, or reach True Platform or Test Cloud.
• A quick curl test through the same proxy works, which makes the Studio failure confusing.
• Your network team runs SSL/TLS inspection, so the proxy re-signs HTTPS traffic with an internal certificate authority (CA).
• You see errors like PKIX path building failed or unable to find valid certification path to requested target.

If most of these sound familiar, read on.

Why correct proxy settings are not always enough

There are two separate layers to get right:

1. Routing: the proxy address and port. This gets your request to the proxy.
2. Trust: the proxy’s CA certificate. This lets Studio trust the certificate the proxy sends back.

If you skip the second layer, Studio rejects the connection even though the route is correct.

This also explains the curl confusion. Many quick connection tests use curl -k, which skips certificate checks, so curl can succeed while trust is still broken. Studio does not skip that check. This is the most common reason behind “the proxy test worked, but Studio still fails.”

Find your case

Each case needs a different fix. Using the wrong fix is why teams go in circles.

Case A: Plain corporate proxy, no SSL inspection

Symptom: Nothing loads at all. Every Katalon domain times out.

Fix: Set Manual proxy configuration in both the Authentication and System proxy sections. See Layer 1 below.

Case B: Proxy settings are correct, but Studio still fails (SSL inspection)

Symptom: The address and port are confirmed, a curl test through the proxy works, but Studio can’t log in or reach True Platform. Often there is no clear error, only a generic connection failure.

Fix: Your proxy is probably intercepting HTTPS and re-signing it with an internal CA. Import that CA certificate into Studio’s own Java truststore. Studio has its own certificate store and does not use the trusted certificates in your OS or browser. See Layer 2 below.

Case C: Mobile testing with remote devices behind a proxy

Symptom: SessionNotCreatedException: PKIX path building failed: ... unable to find valid certification path to requested target when you spy, record, or run mobile tests on remote devices.

Fix: Same cause as Case B, but for remote device sessions. Export the proxy certificate (.cer or .crt) from your proxy server and import it into Studio’s cacerts keystore with keytool. Layer 2 has the exact command.

Case D: Test Cloud connection fails

Symptom: PKIX path building failed when running on Test Cloud, or on cloud grids such as BrowserStack or Sauce Labs.

Fix: Open https://testcloud.katalon.com/healthcheck in Chrome, export the certificate chain (Base64 format), and import it into Studio’s cacerts. Layer 2, Option 2 walks through it with screenshots.

Case E: Your application needs a client certificate

Symptom: Your application under test needs Studio to present a certificate (mutual TLS or client certificate authentication). This is a different problem from trusting the proxy.

Fix: Configure it under Project > Settings > Network > Client certificate settings with a PKCS #12 (.p12) keystore. If you see Could not initialize class org.apache.commons.ssl.KeyMaterial, it’s a known keystore format issue on JRE 17 with a one-line fix. See Client certificates below.

Case F: You need tests running today (temporary only)

Symptom: Your Web Service tests have to run now, and IT can’t give you the certificate yet.

Fix (temporary): Go to Project > Settings > Network and set Certificate Settings to Bypass certificate validation. This only works for Web Service tests and only supports Chrome and Firefox. It turns off a real security check, so use it as a stopgap only. Move to the proper certificate import (Cases B, C, or D) as soon as you can.

Layer 1: Configure the proxy

Do this first, whatever your case.

1. Open proxy preferences: Katalon Studio > Preferences > Katalon > Proxy (on macOS: Katalon Studio > Settings). If you aren’t logged in yet, use Advanced settings on the Welcome screen.
2. Configure both sections separately. Authentication covers login, True Platform, Test Cloud, Katalon Store, and the auto-updater. System covers recording, spying, running tests, and downloading drivers. Setting only one of them is a common half-fix.
3. Select Manual proxy configuration in each section, then enter the proxy Address, Port, and credentials if your proxy needs them.
4. Click Apply or Save, then restart Studio completely. Proxy changes don’t always apply to a session that’s already open.

Advanced settings on the Welcome screen. You can set Manual proxy configuration here before you log in.

Katalon Studio > Preferences > Katalon > Proxy, with Address, Port, and Excludes.

Tip: Under Excludes, list internal hosts that should skip the proxy, for example .internal.company.com. Leave it empty if every request, including internal test targets, must go through the proxy.

Layer 2: Trust the proxy’s certificate

You need this step whenever your proxy does SSL inspection (Cases B, C, and D). Studio ships with its own Java runtime and its own certificate store. An internal CA that your browser already trusts is not trusted by Studio until you import it.

Option 1: Your IT team already has the certificate file

1. Get the proxy certificate from your network or IT team, as a .cer or .crt file.
2. Open a terminal in Studio’s own JRE bin folder, not your system Java:

   # Windows
   <Katalon Studio folder>\jre\bin

   # macOS
   /Applications/Katalon Studio*.app/Contents/Eclipse/jre/bin

3. Import the certificate into Studio’s cacerts keystore:

   # Windows
   keytool -importcert -alias katalon -file "PATH_TO_CERTIFICATE" -keystore ../lib/security/cacerts

   # macOS
   keytool -import -trustcacerts -file "PATH_TO_CERTIFICATE" -alias katalon -keystore ./lib/security/cacerts

4. Enter the keystore password when asked. The default is changeit unless your IT team changed it.
5. Type Yes to trust the certificate. You should see Certificate was added to keystore.
6. Restart Studio so it picks up the updated truststore.

Studio’s own JRE bin folder. Run keytool from here, not from your system Java.

A successful import shows the certificate owner, issuer, and validity, then confirms it was added to the keystore.

Option 2: No certificate file yet? Export it from Chrome

This is useful for Case D, or any time you need the certificate the proxy is presenting right now.

1. Make sure the proxy is on, then open https://testcloud.katalon.com/healthcheck in Chrome. For other cases, use the Katalon domain you’re trying to reach, for example testops.katalon.io.
2. Click the lock icon in the address bar, then Connection is secure, then Certificate is valid.
3. Open the Details tab, click Export, and save as Base64-encoded ASCII, certificate chain.
4. Import the file with the same keytool command from Option 1, then restart Studio.

Click the lock icon to see the certificate the proxy is presenting.

Certificate Viewer > Details tab > Export.

Save as “Base64-encoded ASCII, certificate chain”. This is the format keytool expects.

Admin rights: Importing into this keystore may need you to run the terminal (or Studio) as administrator.

Client certificates (a different problem)

Use this section only when your application under test needs Studio to present its own certificate (mutual TLS). It is not for trusting the proxy.

1. Go to Project > Settings > Network > Client certificate settings and enter the path to a PKCS #12 (.p12) keystore and its password.
2. No keystore yet? Generate one with keytool from your JDK’s bin folder:

   keytool -genkey -alias katalon -keyalg RSA -keystore katalon.keystore
   keytool -export -alias katalon -file katalon.cer -keystore katalon.keystore

3. If you see Could not initialize class org.apache.commons.ssl.KeyMaterial, this is a known issue on Studio 9.x and later (JRE 17), which expects a JKS keystore. Open <Katalon Studio folder>\jre\conf\java.security, change keystore.type=pkcs12 to keystore.type=jks, save, and restart Studio.

Project > Settings > Network > Client certificate settings.

Check that it works

• Restart Studio fully after any proxy or certificate change. Don’t test in a session that was already open.
• Log in or connect to True Platform first. This tests the Authentication proxy path from start to finish.
• Still failing? Check Studio’s log (Help > Show Log, or .metadata/.log in your workspace). If you see PKIX path building failed, the problem is trust (Layer 2), not routing (Layer 1).
• For remote mobile devices or Test Cloud, run that exact scenario again after the import. A successful login doesn’t prove the remote session path works too.

Official docs

• Authentication proxy (login): Configure proxy authentication
• System and Authentication proxy: Configure Proxy Preferences in Katalon Studio
• Mobile and remote devices: Set proxy certificate when connecting to remote devices
• Test Cloud: Unable to find valid certification path to requested target
• Bypass certificate validation: Network settings in Katalon Studio
• Client certificates: Use client certificate for requests in API projects
• Client certificate fix for JRE 17: Unable to send RESTful requests with client certificate

Exact screens, paths, and requirements can vary by Studio version and OS. Screenshots are from docs.katalon.com.

---

Still stuck? Reply below with your Studio version, your OS, which case matches yours, and the exact error from the log. Please remove internal details such as hostnames and IP addresses first.