Why does my Salesforce deployment succeed in sandbox but fail in production?

Three primary reasons. (1) Test coverage: sandbox usually has thousands of records while production has millions, and the larger dataset triggers Apex code paths the sandbox data doesn't reach — code paths that may not have tests. Aggregate coverage stays the same; per-class coverage drops below 75%. (2) Metadata drift: someone made a manual change in production that doesn't exist in sandbox. Your deploy tries to overwrite or reference something that's now incompatible. (3) Profile mismatches: sandbox profiles often grant more permissions than production for testing convenience; production profiles may be locked down such that they can't access a new object the deploy creates, failing validation. Defense: always run a validation deploy against production before a real deploy, and pull production metadata into source control before significant changes.

What's the fastest way to find which class is causing test coverage failure?

Don't read the deploy log — it usually only shows aggregate. Instead, query ApexCodeCoverageAggregate directly after a fresh test run: `SELECT ApexClassOrTrigger.Name, NumLinesCovered, NumLinesUncovered FROM ApexCodeCoverageAggregate WHERE NumLinesCovered != 0 ORDER BY (NumLinesCovered * 1.0 / (NumLinesCovered + NumLinesUncovered)) ASC LIMIT 30`. The lowest-coverage classes are at the top. If the deploy ran tests fresh, this reflects what the deploy saw. If you ran the query before a fresh test run, you're looking at stale coverage from whenever tests last executed — re-run all tests via Setup → Apex Test Execution first to be sure.

How do I deploy to production without downtime?

Use Quick Deploy. The flow: (1) run a validation deploy with `sf project deploy validate --target-org production --test-level RunLocalTests`, which executes everything except the actual write to metadata. (2) If validation passes, Salesforce holds the result for 10 days. (3) Trigger Quick Deploy with `sf project deploy quick --job-id `. Quick Deploy skips test re-execution and writes the metadata, typically completing in under 60 seconds even for hundreds of components. The 10-day window resets on every successful validation, so if you re-validate the same change, the clock starts over. Production users never see the deploy because there's no test-execution wait blocking the transaction.

What's the difference between RunLocalTests, RunSpecifiedTests, and RunAllTestsInOrg?

RunLocalTests runs every test in your org EXCEPT those installed from managed packages. This is the default and right answer for almost all production deploys — managed package tests are the package vendor's responsibility, not yours. RunSpecifiedTests runs only the test classes you list; useful for fast iteration in development sandboxes where you only want to run tests relevant to your change. RunAllTestsInOrg includes managed package tests; only required by Salesforce Security Review for app submissions, never used in normal production deploys. NoTestRun is allowed only for non-Apex changes (UI metadata, layouts) — including any Apex class triggers a forced test run.

How do I find hard-coded Salesforce record IDs in my metadata before they break a deploy?

Two approaches. (1) Source-level: grep your `force-app` directory for the Salesforce ID pattern (15 or 18 char alphanumeric starting with a 3-char object prefix). A regex like `[0-9a-zA-Z]{15}|[0-9a-zA-Z]{18}` is too broad — narrow it to `[a-zA-Z0-9]{3}[a-zA-Z0-9]{12}([a-zA-Z0-9]{3})?` and filter known prefixes (001 = Account, 003 = Contact, 005 = User, etc.). (2) Org-level audit: query MetadataComponentDependency to find any reference between Apex/Flows and specific record IDs — but this only catches typed references, not strings. The robust fix is to replace IDs with Custom Metadata Types: define a CMT row per environment with the right ID, query it from Apex/flow. The fix migrates cleanly between orgs because the CMT structure is the same; the data varies.

What's the right way to order components in a change set or CLI deploy?

Dependency order from leaf to root: (1) CustomObject and CustomField first — everything else references them. (2) ValidationRule, WorkflowRule, Flow next — they reference fields. (3) ApexClass and ApexTrigger — they reference everything above. (4) Profile, PermissionSet, ProfileLayout last — they reference every object/field/class above them. CLI deploys via `sf project deploy start` handle this automatically by analyzing dependencies. Change sets do NOT — Salesforce just deploys in the order components appear in the manifest, which is the order you added them. If a change set fails on a profile, the workaround is to deploy in two passes: components first, then profiles. Or migrate to source-format CLI deploys which solve the ordering problem permanently.

Can I roll back a Salesforce deployment if something goes wrong in production?

Not directly — Salesforce has no native 'undo deploy' button. Rollback strategies, in order of cleanliness: (1) Pre-deploy backup: before the deploy, run a `retrieve` of the target metadata into source control. To roll back, deploy the backup. Works cleanly for everything except destructive changes (deleting fields is not reversible because the data is gone). (2) Destructive changes pre-staged: if your deploy adds a field or class, prepare a `destructiveChanges.xml` ahead of time that removes only what you added. To roll back, deploy the destructive changes file. (3) Manual reversion: for individual broken components, edit in production. Slow and error-prone. The strongest defense is preventive: validation deploys, plus a partial sandbox refreshed weekly so you can rehearse changes against production-shaped data before they ever touch production.

Fix Guide

How to Fix Salesforce Deployment Failures

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

Most Salesforce deployment failures fall into four buckets. (1) Test coverage below 75% — but watch the trap: the org-wide number can be 90% while a single class is at 71%, and that one class blocks the deploy. The error message usually shows only the aggregate. (2) Missing metadata dependencies — your validation rule references a field that doesn't exist in the target org, producing INVALID_CROSS_REFERENCE_KEY. (3) Profile permission references — profiles list every object and field they grant access to, so deploying a profile before the objects it references fails with 'no such entity'. (4) Hard-coded record IDs in flows, validation rules, or Apex — IDs are org-specific and don't survive a deployment. The path to a clean deploy: always run validation (--check-only or change-set 'Validate') first, then Quick Deploy if validation passed within 10 days, and order metadata correctly (objects → fields → automations → profiles last).

Test CoverageMissing DependenciesProfile PermissionsValidation Conflicts

Get AI-Powered Diagnosis See Pricing

The hardest deployment failures are the ones that succeed in sandbox and fail in production — because they're the ones you can't catch in a dry run. Production has more data, different running users, additional metadata that's drifted from sandbox, and frequently a completely different set of profile assignments. A test class that hits 80% coverage in sandbox may hit 73% in production because production data triggers an Apex branch the sandbox data never reached. Same code, different result.

Validation deployments (`sf project deploy validate` or 'Validate' in change sets) are the single highest-leverage tool against this. Validation runs the full deployment including all tests against the target org's data and metadata, but doesn't actually persist the changes. If validation passes, you have 10 days to run Quick Deploy (skips re-running tests) — meaning your real production deploy can complete in under a minute with the test results already locked in. Teams that don't use validation are running production deploys with sandbox-only test results, which is the underlying cause of the 'works in sandbox, fails in prod' loop.

Component ordering inside the deployment matters too. Salesforce processes metadata in a single transaction but validates references as it goes. A change set with [Profile, CustomObject, CustomField] in that order fails because the profile is validated first and the object it references doesn't exist yet. The correct order is reverse-dependency: leaf-level metadata (objects, fields) first, mid-level (validation rules, workflows, flows) next, then policy metadata (profiles, permission sets) last. Most CLI deploys handle this automatically; change sets don't.

Salesforce enforces 75% per-class test coverage for any class included in a deployment AND 75% org-wide coverage at the time of deployment. Quick Deploy preserves validation test results for exactly 10 days — after that you have to re-validate. Both numbers are unchanged from API v40 through Spring '26.

Source: Salesforce Help — Deploy Metadata From a Sandbox to Production

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.

Real-world incidents we've seen

A revenue-ops team whose 18-class deployment failed at the 11th class with 'org-wide coverage 73%'. The aggregate was 88%; one specific trigger handler was at 41% because a recent change introduced an untested error path. Sandbox had no records that hit that path; production had thousands. Fix: write the missing test, redeploy, ship. Lesson: never trust the aggregate coverage number.
A consultancy deploying a complete metadata bundle to a client org that failed because a Flow referenced a custom field renamed two years prior. The Flow was in source control with the old name; the client's production had since renamed the field. Fix: scripted a metadata diff between source-of-truth repo and live org before deploy, surfaced 4 other latent mismatches in the same scan.
A B2B SaaS company whose nightly CI pipeline started failing all deploys after a profile change. Root cause: someone added 'View All Data' permission to the Marketing profile in production via the UI; the source-controlled profile didn't have it. The deploy was overwriting that grant, but a validation rule (also in the same deploy) needed the View All grant to evaluate. The validation rule deployed first, started failing on every Lead create, and the deploy rolled back. Fix: pull production profile state into source control before every deploy.