Working around the Custom Metadata Unknown_Exception issue in Salesforce

One of our users ran into an unusual issue while running a seemingly innocent comparison. When comparing two Salesforce orgs to see the difference between them, Salesforce returned a cryptic error message: Unexpected_Exception: An unexpected error occurred.

Generic error messages like this can me hard to deal with as they give you very little information to work with (as anyone who uses Ant will know). Gearset is all about surfacing and solving deployment issues, so we decided to investigate and find the underlying cause of the error. Thanks to some great feedback from the user in question, we managed to narrow down the cause of this error to very specific scenarios related to Custom Metadata and managed packages. We’ve updated Gearset so it’ll suggest how to work around them more automatically.

The cause of the error: Custom Metadata and managed packages

After collaborating with the user, we found It only occurred in certain very specific situations where the following three criteria were met:

• CustomMetadata was included in the comparison filter
• One of the orgs in the comparison had a managed package installed which contained some CustomMetadata
• The user performing the comparison didn’t have a licence assigned to themselves for that managed package

This bug was triggered with any List Metadata call using the metadata API, including those via Ant, and is one of Salesforce’s known issues.

Working around the error

If you hit this issue during a comparison, there are a number of workarounds you can use to continue with your comparisons and deployments:

1. Turn CustomMetadata off in your comparison filter before performing a comparison in Gearset.
2. Add the user performing the comparison as a licenced user of the managed package (and make sure the licence hasn’t expired).
3. Remove the managed package in question from the org.

Hitting this kind of error can be frustrating, so we’ve now made Gearset a bit smarter to help you diagnose when this issue occurs and work around it.

If you run into this Salesforce bug using Gearset, we’ll warn you immediately and prompt you to follow on of the above steps to resolve the issue. No more hunting through obtuse error messages or searching for the Error ID – just faster, more reliable deployments.

Increase your deployment success rate with Gearset

Have you encountered this error? Want a way to avoid it in the future? Gearset makes all aspects of release management faster and more reliable. Speak to one of our DevOps experts for tailored advice on how to supercharge your release pipeline or start a free 30-day trial to see for yourself.