UNKNOWN_EXCEPTION: An unexpected error occurred. Please include this ErrorId if you contact support

The platform throws this when it hits an internal state it can't recover from. The error includes a unique ErrorId like 1234567890-12345 (12345). That ID is the only way Salesforce support can look up what actually happened.

What to do, in order

1. Save the ErrorId immediately

The ErrorId only exists in the response. Once your code logs and discards it, support can't help. Always capture:

try {
    riskyOperation();
} catch (Exception e) {
    String msg = e.getMessage();
    System.debug('Captured: ' + msg);
    Error_Log__c log = new Error_Log__c(
        Class_Name__c = 'YourClass',
        Message__c = msg,
        Stack_Trace__c = e.getStackTraceString(),
        Created_At__c = System.now()
    );
    insert log;
    throw e;
}

For REST APIs, the response payload includes errorCode + message; the ErrorId is in the message. Log it server-side before showing the user a friendly message.

2. Check the Trust Status site

status.salesforce.com. If your instance shows an active incident, the platform is in a bad state for everyone. Wait it out.

3. File a Salesforce support case

Include:

• The full ErrorId (the bracketed numbers)
• The Apex stack trace if available
• The exact time of the failure
• The org instance name (e.g., NA189, EU45)
• Steps to reproduce, if any

Salesforce support engineers can read internal logs from the ErrorId and tell you what happened on their end.

4. Don't try to "fix" your code from this error alone

UNKNOWN_EXCEPTION is by definition a platform-side issue. Refactoring your Apex to avoid it usually means avoiding a feature entirely (don't deserialize JSON, don't do callouts, etc.) — which is a bad trade. Fix once you know the cause.

Common patterns that trigger it

Some recurring shapes that have known platform issues:

• JSON deserialize of >10 MB — sometimes triggers UNKNOWN_EXCEPTION inside the parser
• Apex sort with non-deterministic Comparable — the platform's sort algorithm has documented issues with comparators that aren't strictly total
• Complex Apex generic types — List<Map<String, List<MyClass>>> and similar deep generics sometimes confuse the runtime
• Bulk API 2.0 with very wide records — over 5,000 fields per record can trigger this

When it appears in production but not sandbox

This is the worst case. Sandbox + production may run different platform sub-versions during release cycles, and a regression in production-only could explain it. File the case ASAP — Salesforce often patches platform bugs within hours of the report when they have a real ErrorId to trace.

What NOT to do

Don't catch and silently swallow:

try {...} catch (Exception e) { /* swallow */ }

That hides the platform issue and lets corruption propagate. Always log + re-throw, even if the user-facing message is generic.