Salesforce error 'System.UnexpectedException'

Why You Cannot Catch This Exception

System.UnexpectedException is thrown by the Salesforce runtime at the platform level and bypasses standard Apex exception handling. It is not a subclass of Exception and cannot be intercepted with try/catch in Apex code. There is no graceful way to handle this exception once it is generated.

How to Handle System.UnexpectedException

Since this exception cannot be caught, the recommended approach is to prevent the conditions that cause it:

1. Review the error message — the message accompanying System.UnexpectedException is usually self-descriptive and points to the root cause (for example, a null pointer, a configuration issue, or a limit violation).
2. Identify the triggering condition — analyze the code path that leads to the exception and add defensive checks (null checks, boundary validations) to prevent the condition from occurring.
3. Contact Salesforce Support if a gack code is present — if the error message contains a Salesforce internal error code (a "gack" code, typically a hexadecimal string), capture this code and provide it to Salesforce Support for investigation.

What Is a Gack?

A "gack" is an internal error report automatically generated and logged by Salesforce when an unexpected server-side exception occurs. Gack codes are used by Salesforce Engineering and Support to trace the root cause of platform-level errors. If you see a gack code in your exception message, open a Salesforce Support case and include the gack code.


What is a Gack?