How to fix UNKNOWN_EXCEPTION in Salesforce deployments

Salesforce returned a generic, uncategorized error, usually pointing to an org-side issue rather than the deployment's own metadata.

Surfaces during: any deploy or DML operation, as a catch-all when nothing more specific applies

What it means

UNKNOWN_EXCEPTION is Salesforce's catch-all error code for failures that don't map to a specific, documented error type. It often indicates an org-level issue, a temporary platform problem, an unhandled exception deep inside a managed package, or a metadata conflict too unusual to categorize, rather than something wrong with the deployment package itself.

Because the code itself carries no diagnostic detail, treat it as a signal to look outward, at instance status, package internals, and prior partial deployments, rather than assuming the fix is somewhere in the metadata you just wrote.

Diagnosis

Common causes

Transient platform issue

A temporary Salesforce infrastructure problem or timeout during the deploy, unrelated to the deployment's content.

Unhandled exception inside a managed package

A managed package's internal logic throws an exception that isn't exposed with a specific error code to subscriber orgs.

Corrupted or conflicting metadata state

The target org has metadata in an inconsistent state, often left over from a previous failed or partial deployment that wasn't cleaned up.

The fix

Retry the deployment
Many UNKNOWN_EXCEPTION failures are transient; a straightforward retry resolves them without any change.
Check Salesforce Trust status for the target instance
Confirm there isn't an active incident or maintenance window on the org's instance before troubleshooting further.
```
https://status.salesforce.com/instances/<your-instance>
```
Deploy a smaller subset to isolate the cause
Split the deployment into smaller pieces to identify which specific component triggers the exception, since the error itself gives no detail.

In practice

How Serpent prevents this

Serpent keeps full deploy logs and history per task, so a retried deployment after an UNKNOWN_EXCEPTION is traceable to the exact attempt that failed instead of getting lost in a one-off CI run. See the Salesforce deployment error library.

Metadata and data in one deployment flow in Serpent

Prevention

Clean up failed deployments completely before retrying

Verify a previous failed or partial deployment didn't leave metadata in an inconsistent state before attempting the next release.

Keep deployments small enough to bisect quickly

Favor smaller, more frequent deployments over rare, large ones, so an opaque failure like this one is fast to isolate by splitting the change.

Log every deploy attempt with enough detail to compare against a retry

Keep deploy IDs and full result logs for every attempt, so if a retry succeeds, you can compare what changed instead of just moving on.

Common questions

UNKNOWN_EXCEPTION, answered

Should I open a Salesforce support case for UNKNOWN_EXCEPTION?

If retrying and isolating the component doesn't resolve it, yes. Because the error carries no detail, Salesforce support can often see the underlying stack trace that the deploy result doesn't expose.

What information should I gather before contacting support?

The deployment or job ID, the exact timestamp of the failure, and the org's instance name; support can look up the underlying error against the deploy ID even when the client-facing message is generic.

Does UNKNOWN_EXCEPTION mean the same failure will always repeat?

Not necessarily. A meaningful share of these failures are transient platform issues that clear on their own, which is why retrying is always the first step, not a last resort.

Start free. No credit card, no install, no commitment.

Set up in under 15 minutes. No DevOps hire needed.

Start free Book a demo