Fix Guide

How to Fix Salesforce Deployment Failures

Step-by-step fix guide with AI-powered diagnosis from BuildForce.

The most common Salesforce deployment failures are: test code coverage below the 75% threshold (check which classes are below threshold, not total coverage), missing metadata dependencies where a component references an object or field that doesn't exist in the target org, profile permission errors when deploying profiles that reference components that haven't deployed yet, and validation rule conflicts when a deployed formula references fields with different API names in the target. BuildForce's deployment health check surfaces all four before you run the deployment.

Test CoverageMissing DependenciesProfile PermissionsValidation Conflicts

Get AI-Powered Diagnosis See Pricing

Symptoms

Deployment returning 'APEX_TEST_SUITE_FAILURE' or 'TEST_LEVEL_INCOMPATIBLE' errors

Error: 'No such column X on entity Y' when deploying validation rules or formulas

Profile deployments failing with permission reference errors

Deployment succeeds in sandbox but fails in production

Change Set deployments stuck in 'Queued' status for hours

Root Causes

Test coverage below 75% for specific classes

Salesforce requires 75% test coverage for the entire org AND for any class being deployed. A class at 74% will block a deployment even if org-wide coverage is 90%. The error message usually only shows total coverage, hiding the specific violating class.

Missing field or object dependencies

Validation rules, workflows, and formulas that reference custom fields require those fields to exist in the target org. Deploying the formula before the field, or referencing a field that was deleted in production, causes INVALID_CROSS_REFERENCE_KEY errors.

Profile permission reference errors

Profiles reference every object, field, and app the user should have access to. If you deploy a Profile before the custom objects and fields it references, the deployment fails. Profiles must deploy after all their dependencies.

Hard-coded IDs in components

Record IDs in Salesforce are org-specific. Validation rules, flows, or Apex code with hard-coded record IDs fail when deployed to an org where those records have different IDs.

How to Fix It — Step by Step

Read the full deployment error log

In Setup → Deployment Status, click 'View Details' on the failed deployment. Expand the 'Component Failures' and 'Test Failures' sections. The summary line often hides the real error — always read the full failure detail.

Fix test coverage failures

Run the specific failing test classes in the target org to see current coverage. Coverage that passes in sandbox may fail in production if production has more records triggering different code paths.

Example

# Check coverage for specific class
SELECT ApexClassOrTriggerId, NumLinesCovered, NumLinesUncovered 
FROM ApexCodeCoverageAggregate 
WHERE ApexClassOrTrigger.Name = 'YourClassName'

Validate dependencies before deploying

Use the Salesforce CLI's 'metadata retrieve' to pull the current production metadata and check that all referenced objects, fields, and components exist before deploying.

Example

sf project deploy validate --source-dir force-app --target-org production --test-level RunLocalTests

Order components correctly in change sets

Deploy in dependency order: custom objects and fields first, then validation rules and formulas, then workflows and flows, then profiles and permission sets last. Never deploy profiles before their referenced components.

Remove hard-coded record IDs

Search your metadata for 18-character Salesforce IDs (format: 001xxxxxxxxxxxxxxx). Replace with dynamic lookups using custom labels, custom metadata, or SOQL queries in Apex code.

Use BuildForce pre-deployment check

Run BuildForce's deployment readiness check before any production deployment. It validates test coverage, identifies missing dependencies, checks for hard-coded IDs, and surfaces profile ordering conflicts.

Let BuildForce diagnose and fix this automatically

Instead of following manual steps, connect your org and let our AI identify exactly what's broken and how to fix it — in minutes.

Book a Demo

Common Questions

More answers about this issue and how to resolve it.

Stop debugging manually. Let AI do it.

BuildForce runs 200+ automated checks across your Salesforce org and tells you exactly what's broken and how to fix it.

Book a Demo View Pricing