Fix Agent SSL Errors on Corporate Networks

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:

javax.net.ssl.SSLHandshakeException: PKIX path building failed
unable to find valid certification path to requested target
sun.security.provider.certpath.SunCertPathBuilderException
Connection failures to https://quemsi.com even though your browser opens the site normally

This commonly affects:

Docker containers on Windows (Docker Desktop) or Linux in a corporate environment
Windows native agent (quemsi-agent.exe) on a company laptop or server
Linux agent binaries installed via the install script or systemd

You do not need this tutorial if

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:

Windows Certificate Manager
Linux /etc/ssl/certs
Docker's OS-level CA bundle (when running the native binary inside a container)

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:

Open https://quemsi.com in your browser on the same machine — it should work.
Check the agent logs for PKIX path building failed.
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

Press Win + R, type certmgr.msc, and press Enter
Navigate to Trusted Root Certification Authorities → Certificates
Find your corporate root CA (look for your company name or a known proxy vendor)
Right-click → All Tasks → Export
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
      - TRUSTSTORE_TYPE=JKS
    volumes:
      - ./certs/corp-truststore.jks:/certs/corp-truststore.jks:ro

Truststore mount path

TRUSTSTORE_PATH must match the path inside the container (left side of the volume mount). If the file is missing at that path, the agent fails with No X509TrustManager implementation available.

Alternatively — 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.trustStoreType=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 `
  -Djavax.net.ssl.trustStoreType=JKS `
  -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 \
  -Djavax.net.ssl.trustStoreType=JKS \
  -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

Troubleshooting

No X509TrustManager implementation available

This means the truststore file could not be loaded inside the container. Check that:

The volume mount path matches TRUSTSTORE_PATH exactly (container path, not host path)
The file exists: docker compose exec agent ls -la /certs/corp-truststore.jks
TRUSTSTORE_PASSWORD matches the password used when creating the JKS file
TRUSTSTORE_TYPE=JKS is set if you used keytool (default format)
The truststore includes public CAs — start from a copy of Java cacerts, then import your corporate CA

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.

Next Steps

Getting Started Guide — connect storage, datasources, and run your first flow
Architecture Overview — understand agent deployment options
Create Read-Only Database User — secure production database access
Explore more tutorials