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

SSL certificate error: self-signed certificate in certificate chain

Encountering a "self-signed certificate in certificate chain" error means your system doesn't trust the SSL certificate, and this guide explains how to identify and resolve the underlying trust issues.

What This Error Means

When you encounter the error "self-signed certificate in certificate chain," it indicates a fundamental trust issue in the Secure Sockets Layer (SSL) or Transport Layer Security (TLS) connection. At its core, an SSL/TLS certificate is a digital document that verifies the identity of a server and encrypts communication. For a browser or client application to trust a certificate, it must be able to trace its origin back to a Certificate Authority (CA) that it already trusts.

A "self-signed certificate" is one that is signed by the same entity that it certifies, rather than by a recognized, third-party Certificate Authority (CA). Imagine a passport that you issued to yourself – no government (CA) has vouched for your identity. Similarly, without a trusted CA's endorsement, a self-signed certificate lacks the external validation needed for widespread trust.

The "certificate chain" refers to the ordered list of certificates that leads back from the end-entity certificate (the one presented by the server) to a trusted root CA certificate. This chain typically looks like: End-Entity Certificate -> Intermediate CA Certificate(s) -> Root CA Certificate. When a self-signed certificate is presented, there is no intermediate or root CA in the chain that the client's operating system or application inherently trusts. The chain effectively ends with itself, hence "self-signed certificate in certificate chain," implying it's the beginning and end of its own trust path from the client's perspective.

The practical consequence is that your client (whether it's a web browser, a curl command, an API client, or a Git client) cannot verify the authenticity of the server it's trying to connect to. It sees the server saying "Trust me, I am who I say I am," but without external validation, the client refuses to proceed, flagging it as a potential security risk or an outright error.

Why It Happens

This error occurs because the client system attempting to establish an HTTPS connection cannot validate the presented certificate against its internal list of trusted root Certificate Authorities. Unlike certificates issued by CAs like Let's Encrypt, DigiCert, or GlobalSign, which have their root certificates pre-installed in most operating systems and browsers, a self-signed certificate does not have this inherent trust.

Here's a deeper dive into the technical reasons:

  1. Lack of a Trusted Root: The primary reason is that the root of the certificate chain, which in this case is the self-signed certificate itself (or an intermediate signed by a self-signed root), is not present in the client's trusted certificate store. Without a path to a trusted root, the client's cryptographic library fails the verification process.
  2. No Public Trust Infrastructure: Public Key Infrastructure (PKI) relies on a hierarchy of trust. Public CAs are audited and globally trusted to issue certificates securely. Self-signed certificates bypass this entire infrastructure, making them suitable only for environments where you explicitly manage trust.
  3. Client-Side Validation Logic: Every SSL/TLS client (browser, curl, openssl, programming language libraries like Python's requests or Java's HttpClient) performs a series of checks during the TLS handshake:
    • Signature Verification: Is the certificate signed by its issuer?
    • Chain Validation: Can the issuer's certificate be traced back to a trusted root CA?
    • Hostname Match: Does the certificate's Common Name or Subject Alternative Name match the hostname of the server it's connecting to?
    • Expiry Date: Is the certificate still valid (not expired or not yet valid)?
      The "self-signed certificate in certificate chain" error typically means the chain validation step failed because the top-most certificate in the provided chain is not considered trusted.

I've seen this in production when a developer mistakenly deploys an internally generated certificate to a public-facing service, or when an internal tool designed for a tightly controlled network is exposed to a broader audience without proper certificate management.

Common Causes

In my experience, this error usually pops up in a few distinct scenarios:

  1. Development and Testing Environments: This is arguably the most frequent cause. Developers often generate self-signed certificates for local servers, internal APIs, or test environments because obtaining a publicly trusted certificate for every internal service can be cumbersome and unnecessary. However, when a different client (another dev's machine, a CI/CD pipeline, or a different microservice) tries to connect, it won't trust these certificates by default.
  2. Internal-Only Services and APIs: Organizations might deploy internal applications, dashboards, or microservices within their private networks using self-signed or privately issued certificates. While perfectly secure within that controlled environment, any external system or even a corporate desktop not configured to trust the internal CA will hit this error.
  3. SSL Inspection by Corporate Proxies/Firewalls (MITM): Many corporate networks deploy security appliances that perform SSL inspection. This "Man-in-the-Middle" (MITM) operation involves the proxy decrypting HTTPS traffic, inspecting it, and then re-encrypting it with its own, internally generated certificate before sending it to the client. If your client machine doesn't have the corporate proxy's root CA certificate installed in its trusted store, it will report a self-signed (or untrusted) certificate error. This is a common pain point for new employees or CI/CD systems.
  4. Misconfigured Load Balancers or Ingress Controllers: In cloud environments (AWS ELB/ALB, Azure Application Gateway, GCP Load Balancer) or Kubernetes with Ingress controllers (Nginx Ingress, Traefik), there are often two SSL connections: one from the client to the load balancer and another from the load balancer to the backend service. If the backend services are using self-signed certificates and the load balancer is configured to validate these backend certificates, or if the load balancer itself is presenting a self-signed certificate to the client, you'll see this error.
  5. Ad-Hoc Tooling or Scripting: Quick scripts or automation tasks that interact with internal services might encounter this if they use default HTTP client libraries that strictly enforce certificate validation without configuration.

Step-by-Step Fix

Resolving this error depends entirely on the context and your intent. Is the self-signed certificate expected and acceptable, or should it be a publicly trusted certificate?

Scenario 1: The self-signed certificate IS expected (e.g., internal dev, testing)

In this case, the goal is to tell your client to trust this specific certificate or the CA that issued it.

  1. Extract the Self-Signed Certificate:
    If you're accessing a web service, you can often download the certificate from your browser's security information. For command-line access, use openssl:
    bash echo -n | openssl s_client -showcerts -connect example.com:443 2>/dev/null | openssl x509 -outform PEM > selfsigned.crt
    Replace example.com:443 with your server's hostname and port. This command extracts the server's certificate into selfsigned.crt.

  2. Add to Your Operating System's Trust Store:
    This makes the certificate trusted system-wide for applications that rely on the OS trust store.

    • On Linux (Debian/Ubuntu-based):
      bash sudo cp selfsigned.crt /usr/local/share/ca-certificates/ sudo update-ca-certificates
    • On Linux (RHEL/CentOS-based):
      bash sudo cp selfsigned.crt /etc/pki/ca-trust/source/anchors/ sudo update-ca-trust extract
    • On macOS:
      Open selfsigned.crt (it should launch Keychain Access), find the certificate, double-click it, expand the "Trust" section, and set "When using this certificate" to "Always Trust."
    • On Windows:
      Double-click selfsigned.crt, click "Install Certificate...", choose "Local Machine," then "Place all certificates in the following store" and select "Trusted Root Certification Authorities."

  3. Configure Application-Specific Trust (if applicable):
    Some applications or libraries (like Java's JVM, Python's requests, Git) might use their own trust stores or offer specific parameters to point to a custom CA bundle. See the "Code Examples" section for specifics.

  4. Temporarily Disable SSL Verification (with extreme caution):
    For quick local development or debugging, you might temporarily disable SSL verification. This is highly discouraged for production or any environment handling sensitive data, as it opens you up to MITM attacks. Only use this if you fully understand the risks and are in a completely controlled, isolated environment.

Scenario 2: The service SHOULD have a publicly trusted certificate (e.g., production public website, external API)

If you're seeing this error on a service that's meant to be publicly accessible and trusted, then someone has deployed a self-signed certificate where a CA-issued one should be.

  1. Identify the Server/Service: Determine which server or load balancer is presenting the self-signed certificate. Use openssl s_client -connect yourdomain.com:443 and look at the Issuer and Subject fields. If they are the same or point to an unknown entity, it's self-signed.
  2. Obtain a Trusted Certificate:
    • Free: Use Let's Encrypt (via certbot or cert-manager for Kubernetes).
    • Paid: Purchase from a commercial CA (DigiCert, GoDaddy, etc.).
  3. Install and Configure the Trusted Certificate:
    • Web Servers (Nginx/Apache): Replace the self-signed certificate and key files with the new CA-issued certificate and its corresponding private key. Update your server block/virtual host configuration.
      nginx # Nginx example ssl_certificate /etc/nginx/ssl/yourdomain.com/fullchain.pem; # Your new cert ssl_certificate_key /etc/nginx/ssl/yourdomain.com/privkey.pem; # Your private key
    • Cloud Load Balancers: Upload the new certificate to your cloud provider's certificate management service (e.g., AWS Certificate Manager (ACM), Azure Key Vault, Google Secret Manager) and configure the listener to use it.
    • Application Servers: Consult your application server's documentation (e.g., Tomcat, Node.js HTTPS module) for how to configure a new certificate and key.
  4. Restart Services: After updating configurations, restart the relevant web server, load balancer, or application service to pick up the new certificate.

Code Examples

Here are some common ways to interact with services presenting self-signed certificates, showing both insecure and trust-based approaches.

1. curl (Command-Line)

  • To verify with a specific CA certificate bundle:
    bash curl --cacert /path/to/selfsigned.crt https://your-selfsigned-server.com
  • To ignore certificate validation (insecure!):
    bash curl -k https://your-selfsigned-server.com

2. Python requests Library

  • To specify a trusted CA certificate:
    ```python
    import requests

    try:
    response = requests.get('https://your-selfsigned-server.com', verify='/path/to/selfsigned.crt')
    print(response.text)
    except requests.exceptions.SSLError as e:
    print(f"SSL Error: {e}")
    * **To ignore certificate validation (insecure!):**python
    import requests
    import urllib3
    urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning) # Suppress warnings

    try:
    response = requests.get('https://your-selfsigned-server.com', verify=False)
    print(response.text)
    except requests.exceptions.SSLError as e:
    print(f"SSL Error: {e}")
    ```

3. git

  • To disable SSL verification for a specific repository (insecure!):
    bash git config http.sslVerify false # Or for a specific remote: git config remote.origin.sslVerify false
  • To specify a custom CA bundle for Git:
    bash git config http.sslCAInfo /path/to/your/custom-ca-bundle.pem

Environment-Specific Notes

The context in which you encounter this error often dictates the best solution.

Cloud Environments (AWS, Azure, GCP)

  • Load Balancers: Cloud load balancers (e.g., AWS ALB/NLB, Azure Application Gateway, GCP HTTP(S) Load Balancing) are frequently configured to terminate SSL at the load balancer. Ensure the certificate uploaded to the load balancer (e.g., in AWS ACM) is publicly trusted. For communication between the load balancer and backend instances, you can use private CAs or self-signed certificates within the VPC, but the load balancer itself needs to be configured to trust these if validation is enabled. This is where I've often seen issues with developers deploying default self-signed certs to instances behind a cloud LB.
  • Managed Services: If you're connecting to managed services like databases (RDS), caches (Redis), or message queues (Kafka), they often provide options for SSL/TLS, sometimes requiring client-side certificates or a specific CA bundle to trust their server certificate. Check the service's documentation carefully.
  • API Gateways: Similar to load balancers, API Gateways (e.g., AWS API Gateway) need proper certificate management for client-facing endpoints.

Docker and Kubernetes

  • Container Images: If your Docker containers need to communicate with internal services using self-signed certificates, the container itself needs to trust those certificates. This often means adding the .crt files to /usr/local/share/ca-certificates/ (or similar for other Linux distributions) inside your Dockerfile and then running update-ca-certificates.
    ```dockerfile
    # Example Dockerfile for adding a custom CA
    FROM python:3.9-slim-buster

    Copy custom CA certificate

    COPY my_internal_ca.crt /usr/local/share/ca-certificates/my_internal_ca.crt

    Update CA certificates

    RUN update-ca-certificates

    ... rest of your Dockerfile

    `` * **Kubernetes Ingress Controllers:** If your Ingress controller is presenting a self-signed certificate, you need to configure it with a properSecretcontaining a CA-issued certificate. Tools likecert-manager` automate the provisioning of Let's Encrypt certificates for Ingress resources.
    * Service Mesh (e.g., Istio): In a service mesh, mutual TLS (mTLS) is often enabled by default, using an internal CA. If you're encountering trust issues, ensure your service mesh configuration for mTLS is correct and that sidecar proxies are properly injecting the trust bundles.

Local Development

  • mkcert: For local development, mkcert is an excellent tool. It creates locally trusted development certificates. It acts as a local CA and adds its root to your system's trust store, so any certificate it generates will be trusted by your browser and applications. This is a much safer alternative to globally disabling verification.
  • Host Files: Be mindful of /etc/hosts entries if you're mapping hostnames to 127.0.0.1 or internal IPs. The certificate's Subject Alternative Name (SAN) must match the hostname you're using.

Frequently Asked Questions

  • Q: Is it ever safe to ignore this error (disable SSL verification)?
    A: Generally, no. Ignoring this error (e.g., using -k with curl or verify=False in Python) bypasses a critical security check, making your connection vulnerable to Man-in-the-Middle (MITM) attacks. Only do so in highly controlled, isolated development environments where you explicitly understand and accept the risk, and never in production for public-facing services.

  • Q: How do I know if my corporate firewall/proxy is causing this?
    A: Check the certificate details in your browser (click the padlock icon). If the issuer of the certificate is your company's name, a proxy vendor (e.g., Zscaler, Palo Alto Networks), or a name you don't recognize for the website you're visiting, it's likely an SSL inspection proxy. You'll need to install the corporate root CA certificate into your system's trust store.

  • Q: Can I use Let's Encrypt for internal services that aren't publicly accessible?
    A: Not directly. Let's Encrypt requires domain validation (proving you own the domain), which typically means your server needs to be publicly reachable on port 80 or 443. For truly internal services that are not exposed to the internet, you'll need to use an internal CA (like HashiCorp Vault's PKI backend) or manage self-signed certificates by distributing their public keys to all clients.

  • Q: What's the difference between "self-signed" and "untrusted"?
    A: A self-signed certificate is one specific type of certificate that is almost always "untrusted" by default by client systems because it lacks a verifiable chain back to a pre-installed root CA. However, an "untrusted" error can also occur for certificates that were issued by a CA if, for example, the CA's root certificate is missing from your system, the certificate has expired, or the certificate chain is broken.

  • Q: My browser shows a different error, but my curl command gets "self-signed certificate in certificate chain." Why?
    A: Browsers often have more sophisticated heuristics and cached data. They might present a user-friendly "Your connection is not private" or "NET::ERR_CERT_AUTHORITY_INVALID" error. curl and other command-line tools provide more direct, low-level error messages like "self-signed certificate in certificate chain" which pinpoint the exact cryptographic failure. The underlying cause is often the same.