Articles

Fix Self-Signed Certificate Trust Errors in Development and CI (2026)

April 18, 2026 5 min read

The core issue is that your system components are refusing to trust certificates signed by a private Certificate Authority (CA) that you control, which is essential for intercepting and inspecting TLS traffic during development or in CI pipelines.

Here are the common reasons this happens and how to fix them:

1. The CA Certificate Isn’t Installed System-Wide

  • Diagnosis: On Linux, check if the CA certificate is present in the system’s trust store.
    sudo ls /etc/ssl/certs/your-ca-name.pem
    On macOS, check Keychain Access. On Windows, check the "Trusted Root Certification Authorities" store.
  • Cause: Most applications and operating systems rely on a pre-defined set of trusted root certificates. If your self-signed CA certificate isn’t added to this list, any certificate signed by it will be considered untrusted.
  • Fix:
    • Linux (Debian/Ubuntu):
      sudo cp your-ca-name.pem /usr/local/share/ca-certificates/
sudo update-ca-certificates
      This copies your CA certificate to the designated directory and then updates the system’s trust store.
    • Linux (RHEL/CentOS/Fedora):
      sudo cp your-ca-name.pem /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust extract
      This places the certificate in the trust source directory and then regenerates the trust store.
    • macOS:
      1. Open "Keychain Access.app".
      2. Drag and drop your your-ca-name.pem file into the "System" keychain.
      3. Find your CA certificate in the list, double-click it, expand "Trust", and set "When using this certificate" to "Always Trust".
    • Windows:
      1. Open certmgr.msc.
      2. Navigate to "Trusted Root Certification Authorities" -> "Certificates".
      3. Right-click "Certificates", select "All Tasks" -> "Import…".
      4. Follow the wizard, selecting "Place all certificates in the following store" and choosing "Trusted Root Certification Authorities".
  • Why it works: These commands and GUI actions explicitly instruct the operating system and its applications to trust your CA certificate as a root of trust.

2. The Application/Service Doesn’t Use the System Trust Store

  • Diagnosis: Check the specific application’s documentation for how it manages trusted certificates. For example, Java applications often use a separate trust store (cacerts or a custom .jks file). Node.js applications might use NODE_EXTRA_CA_CERTS.
  • Cause: Some applications, especially those running in isolated environments or using specific language runtimes, maintain their own trust stores or have mechanisms to load additional CA certificates. They won’t automatically pick up system-wide changes.
  • Fix:
    • Java: Import your CA certificate into the Java trust store.
      sudo keytool -importcert -alias your-ca-alias -file your-ca-name.pem -keystore /etc/ssl/certs/java/cacerts
# You may need to find the correct cacerts path for your JVM installation.
# The default password is often 'changeit'.
    • Node.js: Set the NODE_EXTRA_CA_CERTS environment variable to the path of your CA certificate file.
      export NODE_EXTRA_CA_CERTS=/path/to/your-ca-name.pem
    • Python (requests library): When making requests, explicitly pass the CA bundle path.
      import requests
response = requests.get('https://your-site.dev', verify='/path/to/your-ca-name.pem')
  • Why it works: This ensures that the specific runtime or library used by the application is aware of and trusts your custom CA.

3. Incorrect Certificate File Format or Permissions

  • Diagnosis: Ensure your CA certificate is in PEM format (starts with -----BEGIN CERTIFICATE-----). Check file permissions to ensure the user running the application can read it.
    file your-ca-name.pem
ls -l your-ca-name.pem
  • Cause: Applications might fail if the certificate file is corrupted, in the wrong encoding, or if the process trying to read it doesn’t have read access.
  • Fix: Convert to PEM if necessary (e.g., from DER). Ensure permissions are set appropriately (e.g., chmod 644 your-ca-name.pem).
  • Why it works: Guarantees the certificate is in a readable and standard format for the system or application.

4. Browser Cache or Specific Browser Settings

  • Diagnosis: Try accessing the site in an incognito/private browsing window or a different browser. Check the browser’s certificate management settings.
  • Cause: Browsers can cache certificate trust decisions. Sometimes, specific browser extensions or configurations might interfere with trust validation.
  • Fix: Clear browser cache and cookies. Re-import the CA certificate into the browser’s trust store if it has its own (e.g., Firefox).
  • Why it works: A clean slate for the browser ensures it re-evaluates trust based on the current system/browser settings.

5. CI Environment Specifics (Docker, Kubernetes, etc.)

  • Diagnosis: Inspect the container image or pod configuration. Check if the CA certificate is copied into the container and if trust store update commands are executed within the container’s build or runtime process.
  • Cause: CI environments are often ephemeral. Certificates need to be explicitly installed within the build environment or container image. System-wide trust store updates might not persist or be available without specific steps.
  • Fix:
    • Dockerfile:
      COPY your-ca-name.pem /usr/local/share/ca-certificates/
RUN update-ca-certificates
# Or for Alpine Linux:
# COPY your-ca-name.pem /usr/local/share/ca-certificates/
# RUN update-ca-certificates
    • Kubernetes: Mount the CA certificate as a ConfigMap or Secret into pods that need to trust it, and configure the application within the pod to use it (e.g., via environment variables or custom trust store paths).
  • Why it works: Ensures the CA certificate is present and trusted within the isolated execution environment of the CI job.

6. Outdated CA Certificate or Intermediate Chain Issues

  • Diagnosis: Verify the validity period of your CA certificate and any intermediate certificates in the chain.
  • Cause: If the CA certificate has expired, or if a necessary intermediate certificate is missing or expired, the trust chain is broken.
  • Fix: Re-issue your CA certificate and any subordinate certificates. Ensure your self-signed CA is valid and its expiration date is far in the future.
  • Why it works: A valid, unexpired trust chain is fundamental for TLS.

After addressing these, the next common error you might encounter is related to hostname verification failures if the certificate was not issued for the correct domain names or IP addresses.

Want structured learning?

Take the full Http course →