Originally published on Salesforce Ben
Knowing how to resolve deployment errors is a critical skill for any Salesforce Developer because they are both frequent and time-consuming to debug. Deployment errors are extremely common. When deployments are delegated to one or two people, they naturally develop this skill. But when adopting CI/CD in Salesforce projects, it’s more efficient if the responsibility for deployments is distributed across the team. By enabling source synchronization, Salesforce DX greatly reduces the frequency of deployment errors, although they are still a fact of life for Salesforce Development teams.
Resolving deployment errors is actually what consumes most of the time during deployments. Resolving these errors quickly depends on an understanding of Salesforce, its different types of metadata, and how they inter-depend. This post shares a concise set of suggestions for how to debug deployment errors, followed by tips for reducing deployment errors in the first instance.
9 Steps to Debugging Salesforce Deployment Errors
Here are 9 steps I recommend you take when faced with debugging deployment errors:
- Don’t panic. On large deployments it’s not uncommon to get hundreds of deployment errors. In many cases these errors are closely related to one another and resolving one issue can resolve dozens of related issues.
- If there are a large number of deployment errors, and you’re not using a tool like Copado that organizes them for you, I recommend you copy the list into a spreadsheet to make it easier to manage and work through the list.
- Deployment errors can cascade to cause other errors; this means that errors later in the list can be caused by errors earlier in the list. Therefore the order of the errors is an important clue to resolving them. For example, if a new field can’t be deployed, that can cause a class that uses that field to fail. That class failure can cause the failure of other classes. That in turn can cause the failure of Visualforce pages, which can themselves cause other errors. All of those errors will be resolved once that field is deployed.
- Begin by identifying and deleting any duplicate errors from your list. They will all be resolved in the same way.
- Then identify and delete any dependent errors that are actually caused by earlier errors.
- Then work through the errors from the top down. Take note of any clues such as files, metadata names, or line numbers that are mentioned in the message.
- Being able to view the metadata line by line allows you to take steps like temporarily commenting out lines of metadata that are causing deployment errors so that you can get the main body of the deployment to succeed.
- In the case of large deployments, it can help to temporarily remove pieces of metadata that give persistent errors, so that the main deployment can go through. After deploying the main body of the metadata, you can quickly iterate on the small number of problematic metadata items you’ve isolated. This allows for faster trial-and-error deployments as you work towards a resolution.
- The type of error that is most challenging to debug is in the form ‘An unexpected error occurred. Please include this ErrorId if you contact support: 94477506-8488 (-1165391008)’ This error reflects an internal ‘gack’ or unhandled exception in Salesforce itself. The error number shown is a number from Salesforce’s internal logs, so to get any insight into it you’ll need to file a case with Salesforce and request their Customer Centered Engineering team to look that up in Splunk. In the meantime, you’ll need to do some sleuthing to figure out what caused this error. This debugging is far easier if you’re doing frequent small deployments, since that immediately narrows down the cause. Rather than getting stuck for days, follow the recommendation in point 8 and deploy your metadata in subgroups until you have isolated the source of the problem.
Tips for Reducing Deployment Errors
To reduce the frequency of deployment errors, focus on deploying small batches of changes frequently. In the case of org-based development, ensure that developers are making use of feature branches that run validations of the metadata in their branch against the next higher org (ex: QA). If the metadata in a feature branch validates successfully it is likely to also deploy successfully when merged with the main branches and deployed to higher orgs.
As mentioned earlier, using Salesforce DX scratch orgs for development greatly simplifies the development process since it removes the need to hand-pick metadata items from a source org, a very error-prone process. Instead, Salesforce DX works through pushing and pulling metadata to and from a scratch org in its entirety. In most cases, this ensures that the metadata is coherent.
Getting Help
I highly recommend the Salesforce Stack Exchange group for finding and resolving more obscure deployment errors.
These tips and more can be found in my book Mastering Salesforce DevOps: A Practical Guide to Building Trust While Delivering Innovation.