Home / Tutorials / Fix Agent SSL Errors on Corporate Networks

Fix Agent SSL Errors on Corporate Networks

Resolve SSLHandshakeException and PKIX path building failed when the Quemsi agent runs behind corporate SSL inspection on Windows, Docker, or Linux

When Do You Need This?

Many company networks inspect HTTPS traffic. A proxy decrypts outbound connections, checks them, and re-encrypts them using an internal certificate authority (CA). Your browser trusts that CA because IT installed it on your machine — but the Quemsi agent does not use the Windows or Linux certificate store by default.

You likely need this tutorial if the agent fails to start or cannot connect to Quemsi, and the logs contain errors like:

This commonly affects:

You do not need this tutorial if

  • The agent connects to an on-premises Quemsi server over HTTP (no TLS) on your internal network
  • You are running entirely outside a corporate proxy (home network, isolated lab, etc.)
  • The error is about connecting to your database rather than to the Quemsi API — see our SQL Server TCP tutorial or database connection docs instead

Why This Happens

The Quemsi agent is shipped as a GraalVM native binary. Unlike a regular Java application, it embeds a fixed set of trusted root certificates at build time. It does not automatically pick up certificates from:

When your network's SSL inspection proxy presents a certificate signed by your company's root CA, the agent rejects it because that CA is not in its embedded trust store.

Security note

Only add certificates from your own IT department. Never disable certificate validation or use "trust all" settings in production. Importing your company's official root CA is the correct and secure approach.

Confirm the Diagnosis

Before changing configuration, verify that SSL inspection is the cause:

  1. Open https://quemsi.com in your browser on the same machine — it should work.
  2. Check the agent logs for PKIX path building failed.
  3. Optionally, inspect the certificate your network presents:
# From PowerShell or a terminal on the same host openssl s_client -connect quemsi.com:443 -showcerts

If the certificate issuer is your company (e.g. Zscaler, Blue Coat, Netskope, or an internal CA name) rather than a public CA like Let's Encrypt or DigiCert, this tutorial applies.

Prerequisites

Before You Begin

  • Your Quemsi agent CLIENT-ID and CLIENT-SECRET (from the Quemsi console)
  • Your company's root CA certificate in .crt or .pem format — ask IT if you don't have it
  • Java keytool (included with any JDK 11+, or download a JDK). On Windows, it is typically at C:\Program Files\Java\jdk-21\bin\keytool.exe
  • Write access to create a truststore file and mount it into Docker or reference it from the agent

Step-by-Step Fix

1

Obtain Your Company Root CA Certificate

Option A — Ask IT (recommended)

Request the corporate root CA certificate file used for HTTPS inspection. Most IT teams provide this as a .crt or .pem file.

Option B — Export from Windows

  1. Press Win + R, type certmgr.msc, and press Enter
  2. Navigate to Trusted Root Certification Authorities → Certificates
  3. Find your corporate root CA (look for your company name or a known proxy vendor)
  4. Right-click → All Tasks → Export
  5. Choose Base-64 encoded X.509 (.CER) and save as corp-ca.crt

Option C — Export from the browser

Visit https://quemsi.com, click the padlock icon → certificate details → export the root CA from the chain.

2

Create a Java Truststore

Create a truststore that includes your corporate CA. Run this once on any machine that has keytool:

Windows (PowerShell):

keytool -import ` -alias corp-ca ` -file C:\certs\corp-ca.crt ` -keystore C:\certs\corp-truststore.jks ` -storepass changeit ` -noprompt

Linux / macOS:

keytool -import \ -alias corp-ca \ -file /path/to/corp-ca.crt \ -keystore /path/to/corp-truststore.jks \ -storepass changeit \ -noprompt

If your company uses multiple CAs in the chain, import each one with a different -alias into the same truststore file.

Tip

You can start from the default Java cacerts and add your CA on top, so public sites keep working:

# Windows example — adjust JAVA_HOME to your JDK path copy "%JAVA_HOME%\lib\security\cacerts" C:\certs\corp-truststore.jks keytool -import -alias corp-ca -file C:\certs\corp-ca.crt -keystore C:\certs\corp-truststore.jks -storepass changeit -noprompt
3

Configure the Docker Agent

Mount the truststore into the container and tell the agent to use it.

Docker run (PowerShell on Windows):

docker run --rm ` -e CLIENT_ID=your-agent-id ` -e CLIENT_SECRET=your-client-secret ` -e TRUSTSTORE_PATH=/certs/corp-truststore.jks ` -e TRUSTSTORE_PASSWORD=changeit ` -v C:\certs\corp-truststore.jks:/certs/corp-truststore.jks:ro ` quemsi/quemsi-agent:latest

Docker Compose:

services: quemsi-agent: image: quemsi/quemsi-agent:latest environment: - CLIENT_ID=your-agent-id - CLIENT_SECRET=your-client-secret - TRUSTSTORE_PATH=/certs/corp-truststore.jks - TRUSTSTORE_PASSWORD=changeit volumes: - ./certs/corp-truststore.jks:/certs/corp-truststore.jks:ro

Docker environment variable names

Use CLIENT_ID and CLIENT_SECRET (underscores) in Docker. Names with hyphens like CLIENT-ID are removed by the container shell and will not work.

Older images without TRUSTSTORE_PATH support — pass Java system properties directly:

docker run --rm ` -e CLIENT_ID=your-agent-id ` -e CLIENT_SECRET=your-client-secret ` -v C:\certs\corp-truststore.jks:/certs/corp-truststore.jks:ro ` quemsi/quemsi-agent:latest ` -Djavax.net.ssl.trustStore=/certs/corp-truststore.jks ` -Djavax.net.ssl.trustStorePassword=changeit

Verify

After starting the container, check the logs. The agent should connect successfully and appear as online in the Quemsi console within a minute.

4

Configure the Windows Native Agent (.exe)

If you run the agent directly on Windows (not in Docker), pass the truststore as JVM-style arguments:

target\quemsi-agent.exe ` -Djavax.net.ssl.trustStore=C:\certs\corp-truststore.jks ` -Djavax.net.ssl.trustStorePassword=changeit ` -DCLIENT-ID=your-agent-id ` -DCLIENT-SECRET=your-client-secret

For a persistent Windows service, add these -D flags to the ExecStart line in your service definition or startup script.

5

Configure the Linux Agent (systemd)

If you installed the agent with the Quemsi install script, edit the systemd unit or environment file:

# /etc/systemd/system/quemsi-agent.service (ExecStart line) ExecStart=/usr/local/bin/quemsi-agent \ -Djavax.net.ssl.trustStore=/etc/quemsi-agent/corp-truststore.jks \ -Djavax.net.ssl.trustStorePassword=changeit \ -DCLIENT-ID=${CLIENT_ID} \ -DCLIENT-SECRET=${CLIENT_SECRET}

Then reload and restart:

sudo systemctl daemon-reload sudo systemctl restart quemsi-agent sudo journalctl -u quemsi-agent -f

Alternative: Use HTTP to an On-Premises Server

If you host Quemsi inside your own network (not via https://quemsi.com), you can avoid TLS entirely by pointing the agent at HTTP endpoints:

# application.yml or environment override quemsi-api: server-url: http://your-internal-server keycloak-url: http://your-internal-server

This is suitable for isolated internal deployments where traffic never leaves your network. For cloud-hosted Quemsi (https://quemsi.com), you must configure the truststore as described above.

Troubleshooting

Browser works, agent still fails

This confirms the issue is the agent's trust store, not network connectivity. Double-check that:

  • The truststore file path inside the container matches the mount path exactly
  • You imported the root CA, not just an intermediate certificate
  • The truststore password matches what you configured

Multiple corporate CAs

Some networks use separate CAs for different services. Import every CA in the chain shown by openssl s_client -showcerts, each with a unique -alias.

Permission denied on truststore file

Ensure the agent process can read the truststore. On Linux, chmod 644 on the file is usually sufficient. In Docker, mount as read-only (:ro).

Still failing after truststore setup

  • Verify the agent can reach the network at all (DNS, firewall, proxy hostname)
  • Check whether your company requires an HTTP proxy in addition to SSL inspection — that is a separate configuration
  • Contact your IT team to confirm which root CA signs outbound HTTPS traffic
  • Share agent logs with Quemsi support if the error message differs from PKIX / certificate path errors

Need help?

If you are stuck, gather the agent log output (redact your CLIENT-SECRET), the result of openssl s_client -connect quemsi.com:443, and your deployment method (Docker, Windows exe, Linux). This helps support and IT teams diagnose quickly.

Agent Connected?

Once SSL is resolved, continue with datasource setup, storage configuration, and your first backup flow.

Continue with Getting Started

Next Steps