Terraform Enterprise not able to connect to Redis with mTLS – HashiCorp Help Center

Problem

When using Terraform Enterprise with a Redis instance configured for mutual TLS (mTLS), the archivist process may fail to connect. This issue was introduced with the addition of Redis mTLS support in Terraform Enterprise v202506-1, as documented in the v202506-1 release notes.

The Terraform Enterprise container logs show the following error.

{
  "@level": "error",
  "@message": "failed to start server",
  "@module": "archivist",
  "@timestamp": "2025-08-26T14:09:01.031635Z",
  "err": "failed to create Redis client: failed to append TLS options: failed to create TLS config: failed to load client key pair: tls: private key does not match public key"
}

Prerequisites

Terraform Enterprise is configured to use an external Redis instance with mTLS enabled.
You are using one of the following affected Terraform Enterprise versions:
- v202506-1
- v202507-1
- 1.0.0

Cause

In the affected versions, Terraform Enterprise requires that the client certificate provided for the Redis mTLS connection contains the full certificate chain. If only the client certificate is provided, the TLS handshake fails because the private key does not match the public key within the full chain context expected by the application.

Solutions

There are two approaches to resolve this issue. The recommended solution is to upgrade, but a workaround is available if an immediate upgrade is not possible.

Solution 1: Upgrade Terraform Enterprise

The permanent solution is to upgrade to Terraform Enterprise version 1.0.1 (September 2025) or a later version. Starting with version 1.0.1, the requirement for a full chain certificate was removed, and a standard client certificate is sufficient.

Solution 2: Use a Full Certificate Chain (Workaround)

If you cannot upgrade immediately, you can resolve the issue by providing the full certificate chain for both the client certificate and the CA certificate paths in your Terraform Enterprise configuration.

Update your configuration to point both TFE_REDIS_CLIENT_CERT_PATH and TFE_REDIS_CA_CERT_PATH to the file containing the full chain.

For example, in a docker-compose.override.yml file, the configuration would appear similar to this.

TFE_REDIS_CLIENT_CERT_PATH: /etc/ssl/private/terraform-enterprise_redis/fullchain.crt
TFE_REDIS_CA_CERT_PATH: /etc/ssl/private/terraform-enterprise_redis/fullchain.crt
volumes:
- type: bind
  source: ./certs_redis
  target: /etc/ssl/private/terraform-enterprise_redis

Outcome

After applying either the upgrade or the workaround, Terraform Enterprise will successfully connect to the Redis instance using mTLS.

Additional Information

For more details on Redis mTLS settings, refer to the Terraform Enterprise Configuration Reference documentation.