Debug and resolve Salesforce deployment errors with Gearset’s problem analyzers

There’s nothing worse than finishing development work and building a deployment only for it to fail at the final hurdle. Deployment error messages are often vague, and it’s frustratingly time-consuming to unpick your deployment package to understand what went wrong.

In this article, we’ll cover the common causes of deployment errors and how you can debug them, but we’ll also show you that there’s a better way.

Common Salesforce deployment errors

Salesforce deployments fail for a variety of reasons, but there are a few common errors that are often to blame. Some will alert you with a clear error message that highlights which object or account is causing the deployment failure, while others are more vague. If you’re currently caught out by any of these errors, don’t worry — we’ll dive into how you can debug them in the next section!

1. Missing dependencies

If there are items that need to be created or added to the deployment for it to work, you might face error messages like:

• Method does not exist or incorrect signature
• Variable does not exist
• System.NullPointerException: Attempt to de-reference a null object. Deployment Failed due to Missing Dependencies

There are also specific error messages for missing dependencies on certain metadata types. For example, missing formula field dependencies can return the error message:

Field Discount_Approved__c does not exist. Check spelling

2. Missing deletions

Some items in your target org could be dependent on something that’s being deleted. These items need to be deleted as well in order for the deployment to work.

3. API compatibility problems

If there are differences or changes in API versions between items in your source and target orgs, then you’ll get an error message that’s a variation of:

Property ‘namesegment’ not valid in version 57.0

One of the worst culprits for this type of error message is deploying flows after v44.

4. Mismatched field names due to API version differences

If a field exists in both the source and target but is named differently in each due to the difference in API version then, once again, the deployment will most likely fail.

5. History tracking settings

If a field has history tracking enabled, but the parent object in the target organization doesn’t, the field will need to be removed from the deployment or it will likely fail.

Deployments can also fail if you’ve exceeded the history tracking limit for object fields in your org. If you have history tracking turned on for more than 20 fields, you’ll get an error message like:

objects/Account.object: exceeded the allowed number of fields to track on a given entity

6. Items using features that might not be enabled in the target org

If some standard object fields are being deployed, but they don’t exist in the target organization, this indicates they might use features that aren’t enabled in the target org and you might need to remove them to avoid the deployment failing.

7. Org authentication

For those using change sets, deployment failure might not be caused by your deployment package. Instead, you might be facing an issue with org authentication, giving you an error message like:

This organization isn’t authorized to upload change sets to other organizations

In this case, you’ll need to check the authentication settings of your target org and make sure that you’ve allowed inbound change sets from your source org.

8. An issue on Salesforce’s end

Sometimes, you’ll face an error message that’s actually caused by Salesforce itself:

An unexpected error occurred. Please include this ErrorID if you contact support

In this case, it’s worth checking on forums to see if other members of the community are also seeing this issue with recent deployments, which may suggest Salesforce downtime or an internal problem. Also be sure to check with Salesforce’s support for help.

How to debug Salesforce deployment errors

Whether you’re facing one of the common Salesforce error messages or something you’ve never seen before, there’s a few steps that can help you with debugging deployment errors. These approaches should work with any deployment solution, whether that’s change sets, the Ant migration tool, or a more mature platform like Gearset.

1. Identify issues — Check through the error messages returned by Salesforce and look at which ones are specific to certain objects or accounts. As you’ll have more information, it’s easiest to begin by resolving these specific error messages.
2. Resolve dependent errors — Once you’ve worked through specific error messages, you may find that they were the cause of vague problems that were listed lower down in the deployment failure report. These should now be solved when you run your next deployment.
3. Check for common API errors — It’s easy to miss dependencies or metadata API differences in your deployment package. Methodically work through hierarchies and API versions in your deployment package to check you haven’t fallen into one of these basic pitfalls.
4. Break down into small batches — If you’re still facing a number of errors, it may help to break your deployment down into smaller batches. You could deploy some of the metadata types that aren’t causing issues, or remove specific lines of metadata that are still blocking your deployment.

To future-proof your release process, make sure that you are following deployment best practices for reducing deployment errors in the long run. It’s a good idea to deploy to a sandbox before you deploy into production for testing your release and fixing any deployment errors, before you try to push to your live environment.

Using version control to track all the changes being made in your orgs and org monitoring will give you a clear, long-term understanding of how your orgs are changing and performing. And try to avoid large deployments, as there’s a greater margin for error than releasing in small batches.

Achieve 98% deployment success with Gearset

Gearset’s problem analyzers automatically check your deployment package, catching common causes of deployment failure and suggesting how you can fix them before you deploy. This saves you from having to work out what went wrong with your deployment after it failed, or deploying changes to source control that won’t be deployable to a Salesforce environment.

It’s one of the reasons Gearset’s users deploy successfully 98% of the time!

What are Gearset’s problem analyzers?

As we’ve highlighted, deployments can fail for a number of reasons but there are common causes. We’ve studied the causes of deployment failure — such as missing dependencies or mismatched APIs — and created problem analyzers that can spot those issues in your deployments for you.

Our problem analyzers run before you deploy your package, helping you to catch errors earlier and avoid a failed deployment in the first place. When a problem analyzer picks up a problem, it’ll give you two different options:

1. The problem analyzer can resolve the issue for you with a suggested fix
2. You can resolve the issue manually

This gives you complete control over your deployments, as problem analyzers give you visibility over what changes they’ll make to your deployment, and allow you to resolve issues manually if you’d prefer.

Gearset has almost 100 problem analyzers, designed for smooth deployments. We focus on common causes of deployment failure and supporting teams with the most difficult deployments like CPQ.

Let’s walk through how Gearset’s problem analyzers help with a common deployment error. If you’d like to follow along and see how this works for yourself, why not start a 30 day free trial to replicate this yourself?

NOTE: Gearset’s comparisons have had an upgrade! We’re in the process of updating all our blog posts with the new UI images, but in the meantime you can find out more here.

In the example below, we’re trying to deploy a DiscountPercentage field on the Account object, but without the DiscountRate field on which DiscountPercentage depends.

When you hit Next Gearset’s problem analyzers will run and flag if there’s a problem before your deployment. In this case, there’s a warning.

If you click on this warning, you’ll see that Gearset’s missing dependency problem analyzer has been triggered. The problem analyzer suggests adding the Account object and its subcomponents, which will bring DiscountRate into the deployment package. Or, you can select for the problem analyzer to apply this fix automatically for you. Otherwise, the deployment will fail.

So you can see exactly what effect problem analyzers have had on your deployment package, this information is added to the deployment summary at the end of the deployment flow. And since deployment summaries are permanent records that form part of your audit trail, you’ll now be able to return to earlier deployments and understand why certain items were included or excluded from the deployment package.

In this deployment summary, you’ll notice that Gearset tells us which items were suggested by a problem analyzer. The new DiscountRate field was the missing item that our DiscountPercentage field depends on. The Account object containing these fields, which is otherwise unchanged, has also been brought into the deployment package by the problem analyzer.

Deploy successfully with Gearset

Gearset’s problem analyzers pick up most causes of deployment failure, and can fix them for you. If you want to join the thousands of Salesforce teams already achieving massively improved deployment success, get started with a free 30-day trial of Gearset today!