Overview

When a TLS connection fails, Cato may observe TLS protocol alerts, X.509 certificate validation errors, and internal SSL processing errors. This guide focuses on the fields that are visible in Cato Management Application (CMA) events and explains how to interpret them without assuming that TLS error is caused by the Cato certificate or TLS Inspection.

Important: X.509 certificate validation errors shown in CMA relate to validation of the destination server certificate. They do not indicate a problem with the Cato certificate. TLS protocol alerts in the TLS Error Description field can be generated by either the client side or the server side.

These error values are industry standard. They are derived from the TLS Protocol, which Cato uses for TLS related event validation. As a result, the error names and descriptions reflect standard OpenSSL behavior and may not always map exactly to the observed issue in the environment and could change any time.

Which TLS fields are visible in CMA?

CMA field	What it represents	How to use it
TLS Error Description	A TLS protocol alert observed during the TLS exchange, such as unknown ca, certificate unknown, handshake failure, or bad record mac.	Use this as the primary field for understanding the protocol-level reason the TLS session failed. The alert may originate from either endpoint.
TLS Certificate Error	An X.509 certificate validation problem detected while validating the destination server certificate, such as certificate has expired, hostname mismatch, or self signed certificate in certificate chain.	Use this to identify issues with the destination server certificate or certificate chain. These errors are usually outside the customer endpoint and Cato certificate configuration.
TLS Error Type	Indicates the TLS alert severity reported by the protocol, such as warning or fatal.	Use this as context only. Fatal alerts terminate the session; warning alerts may or may not terminate it depending on endpoint behavior.

How to interpret client-side and server-side alerts

A TLS alert describes what one endpoint reported during the handshake or record exchange. The alert side matters:

Client-side alert: the client rejected something it received or decided the handshake could not continue. In TLS Inspection scenarios, this may include the client rejecting the certificate presented during inspection, rejecting certificate parameters, or failing due to a protocol or cipher mismatch.
Server-side alert: the destination server rejected the handshake or reported a problem with the client-side behavior, protocol parameters, cipher negotiation, or record processing.
CMA displays the alert description, but the alert side is not displayed. Support assistance with diagnostics may be required to confirm which endpoint sent the alert.

Recommended troubleshooting approach

Start with the TLS Error Description field for protocol alerts and the TLS Certificate Error field for destination server certificate validation problems.
Do not assume a certificate-related TLS alert always means the Cato Root CA is missing. First determine whether the alert is a TLS protocol alert or an X.509 validation error.
Compare behavior with TLS Inspection disabled or with the destination bypassed only when appropriate for the application and security policy.
For persistent issues, validate the destination certificate chain, hostname/SAN, supported TLS versions, and cipher suites. Packet captures can help confirm which side sent the alert.

For advanced troubleshooting please refer to TLS Inspection Troubleshooting

Common Errors and Meanings

The following tables describe most common TLS Error (as displayed in the "TLS Error Description" field in the event log), along with their typical causes and general remediation steps.

Certificate and trust-related TLS alerts

TLS Error Description	Typical alert side	Meaning	Common causes and remediation
unknown ca	Client-side	The certificate issuer is not trusted by the peer.	The client may not trust the CA that issued the presented certificate. In TLS Inspection scenarios, confirm that the Cato Root CA is installed and trusted on the endpoint. Also check for missing intermediates or private CA trust requirements.
certificate unknown	Client-side	The certificate was rejected for a generic or unspecified reason.	This is often a broad client rejection. Check certificate validity, key usage, chain completeness, endpoint trust store, and application-specific certificate validation behavior. Compare with TLS Inspection disabled if needed.
bad certificate	Client-side	The certificate failed validation checks.	Possible causes include incorrect key usage, chain issues, hostname mismatch, certificate pinning, or an application rejecting the inspected certificate. Fix certificate trust/chain issues or bypass TLS Inspection for applications that cannot be inspected.
unsupported certificate	Client-side, uncommon	The certificate uses unsupported parameters or algorithms.	Replace weak or deprecated algorithms and keys with modern supported standards.

X.509 destination server certificate validation errors

TLS Certificate Error	Typical source	Meaning	Common causes and remediation
certificate has expired	Server certificate	The destination server certificate is past its validity period.	The website or service owner must renew the certificate and ensure proper certificate rotation.
unable to get local issuer certificate	Server certificate chain	The issuer or intermediate certificate needed to validate the server certificate is missing or not trusted.	The destination server should present the full certificate chain. This is typically resolved by the destination service owner.
IP address mismatch	Server certificate identity	The certificate does not match the IP address used for the connection.	Access the service by its FQDN or update the server certificate SAN to include the IP address when appropriate.
hostname mismatch	Server certificate identity	The certificate does not match the requested hostname.	Correct the server certificate SAN/CN or ensure users access the service using the hostname covered by the certificate.
self signed certificate	Server certificate trust	The destination presents a self-signed certificate that is not trusted by default.	Use a publicly trusted or enterprise-trusted CA certificate, or explicitly trust the certificate where appropriate.
self signed certificate in certificate chain	Server certificate chain	A self-signed certificate appears in the server certificate chain.	Replace the chain with a properly trusted CA chain or ensure the relevant CA is trusted by the validating party.

Protocol, version, and cipher alerts

TLS Error Description	Typical alert side	Meaning	Common causes and remediation
protocol version	Client-side	The endpoints could not agree on a supported TLS version.	Upgrade legacy clients or servers and ensure overlap in supported versions, preferably TLS 1.2 or TLS 1.3.
handshake failure	Client-side	The handshake could not be completed, often because no mutually acceptable parameters were available.	Check supported TLS versions, cipher suites, extensions, SNI behavior, and certificate requirements. Align client and server TLS configuration.
illegal parameter	Mostly client-side; can also be server-side	One endpoint rejected TLS handshake parameters as invalid or unexpected.	Check for incompatible TLS extensions, unsupported groups/signature algorithms, or non-standard client/server implementations. Use packet capture for persistent cases.
insufficient security	Server-side, uncommon	One endpoint considered the negotiated parameters too weak.	Disable obsolete protocols and weak ciphers. Configure modern cipher suites and security policies on the affected endpoint.

Record-layer and miscellaneous TLS alerts

TLS Error Description	Typical alert side	Meaning	Common causes and remediation
bad record mac	Client-side	A TLS record integrity check failed.	May be caused by corrupted traffic, packet loss, middlebox interference, or overlapping inspection/proxy devices. Test path consistency and compare without other interception devices.
decrypt error	Server-side, uncommon	A TLS record or handshake value could not be decrypted or verified.	Check for protocol mismatch, middlebox interference, or implementation issues. Simplify the traffic path and validate with packet capture.
unexpected message	Client-side	A TLS message was received out of sequence.	Usually indicates protocol inconsistency, incompatible implementations, or buggy endpoint behavior. Upgrade affected clients/servers and validate with packet capture if persistent.
internal error	Client-side	A generic failure occurred inside a TLS stack.	May be transient or implementation-specific. If reproducible, collect event details, endpoint logs, and packet captures for support analysis.
unknown	Server-side	A generic or unmapped TLS alert was observed.	Treat as a broad failure indicator. Correlate with destination behavior, packet captures, and server-side logs where available.
decode error	Server-side	A TLS message could not be decoded correctly.	Often caused by malformed TLS messages, protocol incompatibility, or implementation defects. Validate with packet capture and update affected TLS libraries or applications.

Key takeaways

Use TLS Error Description as the main CMA field for TLS protocol alerts.
Use TLS Certificate Error for destination server certificate validation problems.
X.509 errors shown in CMA are about the destination server certificate, not the Cato certificate.
A client-side certificate alert can be related to endpoint trust, certificate pinning, or TLS Inspection trust deployment; a server-side alert usually points to destination server behavior or protocol negotiation.
Confirm alert side with support diagnostics when the CMA event alone is not enough.

For additional guidance, For more information, please refer to Best Practices for TLS Inspection

Understanding TLS errors