SSL/TLS HTTPS / networking ssl tls certificate
Divya Krishnan Cloud & DevOps Engineer

SSL certificate error: self-signed certificate in certificate chain

Encountering "self-signed certificate in certificate chain" means your system doesn't trust the SSL certificate; this guide explains how to fix it.

As a Cloud & DevOps Engineer, I've run into the "self-signed certificate in certificate chain" error more times than I can count. It's a common snag, especially when dealing with internal services, development environments, or tightly controlled corporate networks. While the message itself points to a security measure doing its job, understanding its root causes and how to properly address it is key to unblocking your work without compromising security.

What This Error Means

At its core, this error signifies a breakdown in the chain of trust for an SSL/TLS certificate. When your client (be it a web browser, curl command, Git client, or an application) attempts to establish an HTTPS connection, the server presents its SSL certificate. The client then tries to verify this certificate by tracing its lineage back to a Certificate Authority (CA) that it implicitly trusts.

The "self-signed certificate in certificate chain" message specifically means that during this verification process, the client encountered a certificate that was signed by itself, rather than by a recognized and trusted third-party CA. Furthermore, this self-signed certificate (or the CA that signed it) is not present in your client's list of trusted root certificates. Without a verifiable path to a trusted root, the client cannot confirm the identity of the server and, by default, assumes the connection is not secure, thus aborting it with this error.

It’s crucial to understand that not all self-signed certificates are inherently bad or malicious. Many legitimate internal systems use them. The issue arises when your client's system doesn't have prior knowledge or trust in that specific self-signed certificate.

Why It Happens

This error primarily occurs because the client's system (whether it's an operating system's CA store, a specific application's trust store, or even a browser's built-in list) does not recognize or trust the issuer of the server's SSL certificate.

Here's the sequence of events that leads to this:
1. Server Presentation: A server (e.g., a web server, API endpoint, Git repository) presents an SSL certificate during the TLS handshake.
2. Client Verification: Your client application receives this certificate. It then looks at the "Issuer" field of the certificate to find out who signed it.
3. Chain Building: If the issuer is an intermediate CA, the client expects the server to also provide the intermediate CA's certificate. This process continues, building a "chain" of certificates, until it reaches a root CA.
4. Trust Check: The client then checks if this root CA (or any certificate in the chain) is present in its own local store of trusted root CAs.
5. Failure Point: If the certificate presented by the server is self-signed, and that self-signed certificate is not in the client's trusted store, or if an intermediate certificate in the chain is self-signed and untrusted, the trust verification fails.

The 'why' is ultimately about security. Operating systems and applications maintain a curated list of well-known and trusted CAs (like DigiCert, Let's Encrypt, GlobalSign, etc.). These CAs undergo rigorous audits and security practices. If a certificate isn't signed by one of these trusted entities, the client cannot guarantee that it's connecting to the legitimate server and not an imposter attempting a Man-in-the-Middle (MITM) attack.

Common Causes

Based on my experience in various environments, here are the most common scenarios that lead to the "self-signed certificate in certificate chain" error:

  • Development and Testing Environments: This is perhaps the most frequent culprit. For local development servers, internal APIs, or non-production test environments, developers often generate self-signed certificates to enable HTTPS without the cost or complexity of obtaining publicly trusted certificates. My first thought when I see this error is often "Is this a dev server?"
  • Internal Corporate Services: Many organizations run internal applications, Git repositories (like GitLab or GitHub Enterprise instances), or artifact repositories (like Artifactory or Nexus) that are not exposed to the public internet. These services often use certificates issued by the company's internal Certificate Authority (PKI) or even directly self-signed certificates. If your client machine isn't configured to trust the corporate CA, you'll hit this error.
  • SSL Interception Proxies (Man-in-the-Middle by Design): In enterprise networks, it's common for security appliances (like firewalls or proxies) to perform "SSL inspection." This involves decrypting HTTPS traffic, inspecting it for threats, and then re-encrypting it before sending it to the destination. During re-encryption, the proxy presents its own certificate, often issued by an internal CA that isn't trusted by default by client machines. I've seen this in production when engineers connect to external services via the corporate network.
  • Misconfigured Servers or Incomplete Certificate Chains: Sometimes, the server itself is misconfigured. While it might have a valid certificate issued by a trusted CA, it might fail to send the entire certificate chain (i.e., missing intermediate CA certificates) during the TLS handshake. When the client receives only the server's end-entity certificate and can't build the chain back to a trusted root, it can sometimes present as a self-signed error.
  • Outdated Client CA Bundles: Less common now with modern operating systems and browsers, but possible with older systems or specialized tools. If the client's trusted CA bundle is outdated, it might not recognize newer root CAs, leading to validation failures.
  • Containerized Applications: When working with Docker or Kubernetes, a container might not inherit the host's trusted CA store. If an application inside a container tries to connect to a service using a self-signed or internal corporate certificate, the container itself needs to be explicitly configured to trust that certificate.

Step-by-Step Fix

Addressing this error typically involves one of two main approaches: either configuring the server with a trusted certificate or configuring the client to trust the existing certificate.

  1. Identify the Untrusted Certificate:
    The first step is always to understand which certificate is causing the problem and who issued it.
    ```bash
    openssl s_client -showcerts -connect your.server.com:443