Click Deploy Errors: Why Salesforce Deployments Fail and How to Fix Them

TL;DR: A click deploy rarely fails because of the button. It fails because the Salesforce Metadata API rejects the package, and almost every rejection falls into five groups: a missing dependency, too little test coverage, an API version the target does not know, a platform size limit, or a change the API cannot make. Read the first error, fix the cause in the source, and validate again before you deploy.

What happens when you click deploy in Salesforce?

Whatever tool you click in, the same thing happens underneath. The tool builds a package.xml manifest and a .zip of the selected metadata, sends it to the Metadata API, and Salesforce compiles it, runs Apex tests at the chosen test level, and saves the result. If you are new to point-and-click tools, start with how ClickDeploy works and what it costs.

Two platform rules explain most surprises:

• It is all or nothing by default. One error rolls back the whole deployment. The Salesforce CLI reference offers a flag to ignore errors and skip the rollback, and says never to use it when deploying to production.
• Sandboxes and production test differently. The default level runs no tests in a sandbox, while production deployments that include Apex classes or triggers run all local tests. That is why a deploy can pass in UAT and fail in production.

Why do click deployments fail?

1. A dependency is missing

The package references something the target org does not have: a field without its object, a Flow without the fields it reads, a child object without its parent. Copado Essentials, the tool formerly called ClickDeploy, documents a classic case: deploying a detail object alone returns Cannot set sharingModel to ControlledByParent on a CustomObject without a MasterDetail relationship field. Its fix is to add the parent object to the deployment, even if it has not changed.

2. Apex test coverage is too low

Salesforce requires at least 75% of your Apex to be covered by unit tests to deploy to production, and every trigger needs at least one covered line. If you choose RunSpecifiedTests, the bar changes: the tests you name must cover 75% of each class and trigger in the package on its own. The fix is better tests, not a different test level.

3. The API version is newer than the target

An error such as Invalid api version usually appears around a release window, when your sandbox already runs the next Salesforce release and production does not. Winter '27 is a live example: sandboxes moved to preview in late August 2026, while production instances upgrade over several weekends into October, so check your instance on Salesforce Trust. Copado's guidance is to set the component's API version back to one production supports, then redeploy.

4. The package is too big

Salesforce's own deploy library, source-deploy-retrieve, warns as a deployment approaches the Metadata API limits of 10,000 files and about 39 MB zipped. Wildcard selections and whole-object deploys hit these first. Split the release, or ship only what changed with delta deployments.

5. The change is one the API will not make

• Active Flows. Copado's Flow guide notes you cannot deploy a Flow version that is active in the target org. Clone it to a new version in the source, deploy that, and activate it in the target. It also warns that deploying the FlowDefinition component tends to return invalid version number.
• Picklist conversions. A regular picklist cannot be converted to a global value set by deployment. Copado's workaround is to create a new field on the global value set and retire the old one.

How do you troubleshoot a failed click deploy, step by step?

1. Read the first error, not the last. One missing field can cascade into dozens of follow-on errors.
2. Name the group. Dependency, coverage, version, size or unsupported change. Each has a different fix.
3. Fix the source, not the target. Patching production by hand makes the next comparison lie.
4. Validate again. Run a check-only deployment with the same test level production will use.
5. Deploy the validated package. Our click deploy checklist covers test levels and quick deploy.

What does a successful click deploy not tell you?

A green deploy only means Salesforce accepted the package. It does not mean the target matches the source:

• Disabled profile permissions. Copado documents that the Metadata API leaves disabled user permissions out of retrieved profiles, so a permission switched off in the source can stay on in the target.
• Deletions. Removals travel separately, as pre- or post-deploy destructive changes.
• Someone else's work. Org-to-org deploys keep no shared history, so a second deploy can silently overwrite the first. Deploying from a Git branch fixes that.

Who is Tekunda, and how does Serpent reduce failed deploys?

Tekunda is the Salesforce consulting and product company behind Serpent, the DevOps platform it runs on its own client delivery. Serpent keeps the click-to-select experience, but every change travels through Git, a pull request and a validation with Apex tests before it reaches the next org, with AI code review on every plan, including the free one. It installs nothing in your org. Teams on Copado Essentials, Gearset, Salto, AutoRABIT, Flosum or Blue Canvas can follow our migration path, and more how-tos live in the SF Guides library.

FAQ

Why does my deployment pass in a sandbox but fail in production?

Sandboxes run no Apex tests by default, while production runs local tests and enforces 75% coverage. Validate against production with the same test level first.

What does "invalid api version" mean?

Your component uses an API version the target org does not support yet, usually during a release window. Lower the component's version and redeploy.

Can I ignore errors and deploy anyway?

The Salesforce CLI has an ignore-errors flag that skips the rollback, but its own reference says never to use it in production.

How many components can one deployment hold?

The Metadata API caps a deployment at 10,000 files and about 39 MB zipped. Split larger releases.