ory/hydra · error

tls configuration is invalid

Error message

tls configuration is invalid

What it means

ErrInvalidCertificateConfiguration is returned when TLS material was provided but is not valid — the loading path exhausts all supported configurations (env/base64 and file sources) without producing a usable certificate. It indicates a malformed or incomplete TLS setup rather than a missing one.

Source

Thrown at oryx/tlsx/cert.go:39

	"math/big"
	"os"
	"path/filepath"
	"slices"
	"sync/atomic"
	"testing"
	"time"

	"github.com/pkg/errors"
	"github.com/stretchr/testify/require"

	"github.com/ory/x/watcherx"
)

// ErrNoCertificatesConfigured is returned when no TLS configuration was found.
var ErrNoCertificatesConfigured = errors.New("no tls configuration was found")

// ErrInvalidCertificateConfiguration is returned when an invalid TLS configuration was found.
var ErrInvalidCertificateConfiguration = errors.New("tls configuration is invalid")

// HTTPSCertificate returns loads a HTTP over TLS Certificate by looking at environment variables.
func HTTPSCertificate() ([]tls.Certificate, error) {
	prefix := "HTTPS_TLS"
	return Certificate(
		os.Getenv(prefix+"_CERT"), os.Getenv(prefix+"_KEY"),
		os.Getenv(prefix+"_CERT_PATH"), os.Getenv(prefix+"_KEY_PATH"),
	)
}

// HTTPSCertificateHelpMessage returns a help message for configuring HTTP over TLS Certificates.
func HTTPSCertificateHelpMessage() string {
	return CertificateHelpMessage("HTTPS_TLS")
}

// CertificateHelpMessage returns a help message for configuring TLS Certificates.
func CertificateHelpMessage(prefix string) string {
	return `- ` + prefix + `_CERT_PATH: The path to the TLS certificate (pem encoded).

View on GitHub (pinned to 4174065ffb)

Solutions

1. Verify the certificate and key form a matching, parseable PEM pair (openssl x509/x509keypair check)
2. Provide the full configuration for one source: both cert+key as base64, or both as valid file paths
3. Check file permissions and mount paths so the key/cert files are readable at runtime
4. Re-issue or re-export the certificate if it fails to decode; confirm correct base64 encoding without newlines
5. Compare against a known-good TLS configuration (e.g. from a working deployment)

Example fix

// before
Certificate(base64Cert, "", "", "") // key missing -> ErrInvalidCertificateConfiguration
// after
Certificate(base64Cert, base64Key, "", "") // complete PEM pair

if certPEM != "" {
	if _, err := base64.StdEncoding.DecodeString(certPEM); err != nil {
		return fmt.Errorf("TLS_CERT is not valid base64: %w", err)
	}
}
if _, err := tls.X509KeyPair(pemCert, pemKey); err != nil {
	return fmt.Errorf("cert/key invalid or mismatched: %w", err)
}

func isInvalidCertConfig(err error) bool {
	return errors.Is(err, tlsx.ErrInvalidCertificateConfiguration)
}

certs, err := tlsx.Certificate(certPEM, keyPEM, certPath, keyPath)
if err != nil {
	if errors.Is(err, tlsx.ErrInvalidCertificateConfiguration) {
		return nil, fmt.Errorf("TLS config invalid: check cert/key pairing and formats")
	}
	return nil, err
}

When it happens

Trigger: Calling Certificate() with some TLS inputs set, but none forming a complete valid pair — e.g. only CERT base64 without KEY, PEM data that fails to decode or parse, or paths pointing at unreadable/invalid files so the loader falls through all branches to cert.go:123.

Common situations: Corrupted or truncated base64-encoded certificates; a certificate whose key does not match; secret mounts containing the wrong files; rotation scripts writing half-updated certificates; unsupported key or cert formats passed to the loader.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• no tls configuration was found
• cookiex: purpose must be non-empty and must not contain a pi
• cookiex: at least one secret is required
• file loader disabled
• http(s) loader disabled

AI-assisted analysis of ory/hydra@4174065ffb (2026-09-03). Data as JSON: /api/errors/b548e8755f570554. Report an issue: GitHub.