System.UnexpectedException: salesforce system error / Apex script unhandled exception

This is the platform telling you that something inside Salesforce hit an unexpected state. Your Apex didn't raise this — the runtime did. Common causes are obscure, platform-side issues that no amount of code rewriting will fix.

When this is your fault

Sometimes it actually is — a corner case the platform doesn't validate cleanly throws this instead of a clearer message:

• A Map<String, Object> containing a circular reference that fails to serialize for callout.
• A custom Apex type implementing Comparable whose compareTo returns inconsistent results (the sort goes haywire).
• A static initializer that references a class that hasn't been compiled yet (deploy ordering issue).
• A JSON.deserialize of a payload with null for a primitive field.

If your code change immediately preceded the error, suspect those first. Often the fix is to defensively handle the input shape before passing it to the platform.

When it's the platform's fault

If your code didn't change and this started appearing, three places to check:

1. Trust Status (status.salesforce.com) — your instance might be in a known incident.
2. Recent Salesforce releases — major upgrades sometimes introduce regressions in obscure code paths.
3. Setup → Support → My Cases — see if other admins in your org reported it.

For a real platform issue, file a Salesforce support case with:

• The full stack trace
• The request ID (visible at the top of the error page in Lightning, or in the response headers for API calls)
• The minimal Apex that reproduces it
• The exact time + your org instance name

Salesforce support engineers can lookup internal logs from the request ID; without it, they're guessing.

Don't catch it

// ❌ Anti-pattern
try { ... } catch (System.UnexpectedException e) { /* swallow */ }

UnexpectedException is the platform telling you the runtime is in an unknown state. Catching and swallowing it lets your code proceed in a corrupted state — silently. Let it propagate. If it's killing a user-facing flow, surface a friendly message to the user but log the raw exception for your team to triage.

A workaround pattern for known platform quirks

Some recurring UnexpectedException patterns have community-known workarounds:

• JSON deserialization of large payloads: chunk the input and deserialize in smaller batches.
• Apex sort with custom Comparable: ensure compareTo is strictly total (a vs b returns the opposite of b vs a, transitive across triples).
• Async Apex with serialized state: keep instance variables to primitives + simple collections; avoid Map<String, Object> with mixed types.

A diagnostic that occasionally works

Wrap suspicious code in a savepoint:

Savepoint sp = Database.setSavepoint();
try {
    suspiciousOperation();
} catch (System.UnexpectedException e) {
    Database.rollback(sp);
    System.debug('UnexpectedException at: ' + System.now() + ' — ' + e.getStackTraceString());
    throw new IntegrationException('Platform error; data rolled back. ID=' + UserInfo.getUserId(), e);
}

This at least leaves your DB clean and gives you a logged stack trace to send to support.