Deployment Error Diagnosis

Deployment Error Diagnosis

Salesforce deploy errors are notorious for being technically correct but actionably opaque. "INVALID_CROSS_REFERENCE_KEY" tells you a reference is broken, not which one. "Field type cannot be changed" doesn't tell you which records are using the field. "Dependent class is invalid and needs recompilation" implicates some class but not yours.

This skill is a translation layer: error message → actual cause → actual fix. It assumes you have the deploy log; the input is the error string, the output is the next action.

What this skill is NOT. Pipeline design (CI/CD shape, environment strategy) is devops/sfdx-cicd-pipeline. Change-set construction mechanics — admin/changeset-builder. This skill is for the "my deploy failed; what does this mean" moment.

Before Starting

• Capture the FULL error message. Not just the first line — the dependent-metadata error often appears 30 lines down.
• Capture the package contents. Knowing what's IN the package is half the diagnosis.
• Note source / target environments. A deploy that works prod → sandbox may fail dev → prod for permission reasons.
• Note whether tests ran. "Tests didn't run" vs "tests ran and failed" are different problems.

Core Concepts

The most-common error patterns

package.xml ordering smells

package.xml doesn't have explicit ordering — the platform resolves dependencies. But:

• Wildcards (<members>*</members>) with explicit <members> for the same type confuse the platform; pick one.
• Profile / Permission Set delta must include the metadata it references. A profile delta saying <field>Account.Custom__c</field> with <editable>true</editable> requires Account.Custom__c in the package OR pre-existing in target.
• PermissionSetGroup must be deployed AFTER its component PermissionSets.
• Flow with subflow references requires the subflow active in target (or in the package as Active).

Profile / Permission Set deltas

Profiles and permission sets are notoriously verbose; SFDX often exports them in full (every FLS line for every field). Deploying a full profile against a target with different fields produces errors per missing field.

The cleanest patterns:

• Permission Set Groups instead of profiles where possible.
• Profile delta scoping — only the fields / objects in the package, not the full profile.
• profileObjectAccesses + profileFieldLevelSecurities in package.xml so SFDX exports just those entries.

Test coverage failures

Salesforce requires 75% test coverage org-wide for production deploy. Per-class coverage is also tracked. Failures present as:

Average test coverage across all Apex Classes is 73%, at least 75% is required.

Or:

Failed: classes/MyHandler — only 60% covered

Diagnosis: query ApexCodeCoverageAggregate to find low-coverage classes; add tests; redeploy.

Common Patterns

Pattern A — Cannot change type field migration

When to use. Need to change Region__c from Text to Picklist.

Sequence.

1. Create new field Region_v2__c of the new type.
2. Migrate data: SOQL update setting v2 from v1 mapping rule.
3. Update all references (Apex, formulas, validation rules, reports, dashboards, page layouts) to use v2.
4. Delete v1 in a separate deploy.

The "delete v1" step requires v1 to have no remaining references — the deploy fails if it does, with a more useful error listing the references.

Pattern B — Profile / permset cross-reference fix

When to use. Error: Cannot find field Account.Custom_X__c referenced in profile.

Diagnosis.

1. Confirm the field exists in source.
2. Confirm the package.xml includes the field (either explicitly or via <members>*</members> for CustomField).
3. If yes: target may have a stale profile referencing the field. Add the field to the package.
4. If no: the field needs to be added to the package, OR the profile delta needs to omit the FLS line for the missing field.

Pattern C — Test coverage failure on a deploy

When to use. Production deploy fails on coverage threshold.

Diagnosis.

1. SOQL: [SELECT ApexClassOrTrigger.Name, NumLinesCovered, NumLinesUncovered FROM ApexCodeCoverageAggregate WHERE NumLinesUncovered > 0 ORDER BY NumLinesUncovered DESC LIMIT 20].
2. The classes with the most uncovered lines are the targets.
3. Write tests for them in the same package as the deploy.
4. Re-run.

For "average across all classes" failures, the calculation is total-lines-covered / total-lines. One fully-covered new class can lift the average enough; check a representative high-line-count class first.

Pattern D — Flow active / inactive deploy errors

When to use. "Cannot deploy a package containing inactive flow" or "Active flow refers to inactive subflow".

Approach.

• Set <status>Active</status> on the top-level flow.
• For subflows referenced by an active flow, also set Active.
• For flows being retired, set <status>Obsolete</status> — doesn't fail the deploy, doesn't run new invocations, preserves history.

Pattern E — Cleaning up entity is in use for field deletion

When to use. Field deletion blocked by "entity is in use".

Diagnosis.

• The field is referenced somewhere active. Search Apex / formulas / validation rules / reports / dashboards / Flow / layouts.
• The "Where Is This Used?" Setup feature shows references but isn't always exhaustive.
• For comprehensive search: SFDX sf data query + grep across source.

Approach.

1. Inventory references; deactivate / replace each.
2. Deploy the deactivations / replacements as a separate package.
3. Then deploy the field deletion.

Decision Guidance

Recommended Workflow

1. Capture the full error message + the deploy package contents.
2. Match against the error patterns above. Most production deploy errors fit a known shape.
3. For unmatched errors: search the salesforce.stackexchange.com Q&A for the exact error string.
4. Apply the fix in source control. Don't hotfix the target org directly; the source-target gap creates more errors.
5. Re-run the deploy.
6. For deploys that keep failing: capture the sequence of errors. The order tells you the dependency graph.

Review Checklist

• Full deploy error message captured (not just first line).
• Package contents reviewed.
• Source / target environments noted.
• Test-coverage status (ran / didn't run / failed) noted.
• Fix applied in source control, not the target org.
• Dependent metadata included in the package.
• Profile / permset delta scoped to the package's metadata.

Salesforce-Specific Gotchas

1. Cannot change type requires data clearance. Type changes are restricted on populated fields. (See references/gotchas.md § 1.)
2. Profile / permset full-export deploys verbose deltas that fail per missing field. (See references/gotchas.md § 2.)
3. Test coverage org-wide vs per-class — failures can be either; diagnose appropriately. (See references/gotchas.md § 3.)
4. <members>*</members> + explicit <members> for the same type confuses the platform. (See references/gotchas.md § 4.)
5. Flow retirement should be Obsolete, not delete. Preserves history; doesn't run new invocations. (See references/gotchas.md § 5.)
6. entity is in use rarely surfaces every reference. Search source comprehensively, not just Setup → Where Is This Used. (See references/gotchas.md § 6.)
7. PermissionSetGroup deploys after component PermissionSets. Order matters for groups. (See references/gotchas.md § 7.)

Output Artifacts

Related Skills

• devops/sfdx-cicd-pipeline — pipeline design where these errors show up.
• admin/changeset-builder — change-set-specific deployment.
• apex/test-class-standards — test coverage that prevents Pattern C failures.
• admin/order-of-execution — when "deploy succeeds but behavior is wrong" comes from save-time ordering.