gravitational/teleport · error

basic constraints not valid (BasicConstraintsValid=false)

Error message

basic constraints not valid (BasicConstraintsValid=false)

What it means

validateOverrideCertificate requires BasicConstraintsValid to be true on the override certificate. Even when IsCA is true, a missing or malformed basic constraints extension means Go cannot verify the CA constraint, so the certificate is rejected as unsafe for use as an issuing CA.

Source

Thrown at lib/subca/parsed.go:349

	// Trace not used on purpose. Errors are trace-wrapped up in the chain.
	certClusterName, err := tlsca.ClusterName(cert.Subject)
	if err != nil {
		return fmt.Errorf("cluster name: %w", err)
	}
	if certClusterName != clusterName {
		return fmt.Errorf(
			"incorrect cluster name %q (expected %q)",
			certClusterName,
			clusterName,
		)
	}

	// Verify certificate constraints.
	switch {
	case !cert.IsCA:
		return errors.New("not a CA certificate (IsCA=false)")
	case !cert.BasicConstraintsValid:
		return errors.New("basic constraints not valid (BasicConstraintsValid=false)")
	case cert.KeyUsage&x509.KeyUsageCertSign == 0:
		// Usage names per Go 1.26.1.
		// https://cs.opensource.google/go/go/+/refs/tags/go1.26.1:src/crypto/x509/x509_string.go;l=23
		return errors.New("missing KeyUsage keyCertSign")
	case cert.KeyUsage&x509.KeyUsageCRLSign == 0:
		return errors.New("missing KeyUsage cRLSign")
	case cert.NotBefore.After(cert.NotAfter):
		return errors.New("NotBefore > NotAfter")
	}

	return nil
}

View on GitHub (pinned to 1283425b60)

Solutions

1. Re-issue the certificate with the Basic Constraints extension present and critical, e.g. CA:TRUE.
2. Check with 'openssl x509 -in cert.pem -text' that the 'X509v3 Basic Constraints' section exists and shows CA:TRUE.
3. If you control generation code, set template.BasicConstraintsValid = true and template.IsCA = true before x509.CreateCertificate.

Example fix

// before
template := &x509.Certificate{ IsCA: true } // BasicConstraintsValid missing
// after
template := &x509.Certificate{
  IsCA:                  true,
  BasicConstraintsValid: true,
  KeyUsage:              x509.KeyUsageCertSign | x509.KeyUsageCRLSign,
}

if !cert.BasicConstraintsValid {
    return errors.New("override cert missing valid Basic Constraints (CA:TRUE)")
}

When it happens

Trigger: Supplying an override certificate whose X.509 Basic Constraints extension is absent (cert.BasicConstraintsValid=false), typically when IsCA may be true but the extension was never emitted during issuance.

Common situations: Certificates generated by custom/legacy tooling that omits the basicConstraints extension; hand-crafted certs via Go's x509.CreateCertificate without setting BasicConstraintsValid; old internal PKI material.

Related errors

• not a CA certificate (IsCA=false)
• chain not allowed with an empty certificate
• missing KeyUsage keyCertSign
• NotBefore > NotAfter
• nil certificate override

AI-assisted analysis of gravitational/teleport@1283425b60 (2026-09-02). Data as JSON: /api/errors/7cfdda8be9baccc2. Report an issue: GitHub.