Destructive Changes Deployment

Destructive Changes Deployment

This skill activates when a practitioner or agent needs to delete metadata components from a Salesforce org using Metadata API or the sf CLI. It covers all three manifest variants, dependency sequencing, components that cannot be deleted via API, and the correct CLI flags.

Before Starting

Gather this context before working on anything in this domain:

• Confirm the exact API name and metadata type of every component to be deleted. Wildcards are not supported in destructiveChanges manifests — every member must be listed explicitly.
• Identify all components that reference the target component. A deletion will fail with a deployment error if any active component still holds a reference (e.g., a field referenced in a validation rule, a class referenced in a trigger, a component embedded in an active Lightning page).
• Know which components are permanently undeletable via the Metadata API: Record Types, Picklist values (field values), and active Flow versions cannot be deleted through a deployment. These require manual admin action in Setup.

Core Concepts

The Three Manifest Variants

The Metadata API supports three placements for destructive operations within a deployment, each controlled by the filename. All three files share the same XML schema as a standard package.xml.

destructiveChangesPre.xml — Deletions are processed before the additions and updates in the accompanying package.xml. Use this when the component being deleted would conflict with a new component being deployed (e.g., renaming a field by deleting the old one and creating the new one, where the old name must be cleared first).

destructiveChanges.xml (plain name) — The platform processes deletions at the same time as additions. In practice this behaves like a pre-deployment deletion. This is the legacy format from the Ant Migration Tool era and remains valid.

destructiveChangesPost.xml — Deletions are processed after all additions and updates in package.xml have landed. This is the required variant when the component being deleted is still referenced by another component that is itself being updated in the same deployment. The new version of the referencing component must land first (clearing the reference) before the deleted component can be removed.

All three files must be included inside the same deployment package as a package.xml. When using sf CLI flags, an empty package.xml (specifying only the API version) may be used as the companion manifest.

Manifest XML Structure

Every destructive manifest follows the same schema as package.xml. The <version> element is omitted from destructive manifests — version lives only in package.xml. Each <types> block groups members by metadata type.

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>MyObject__c.OldField__c</members>
        <name>CustomField</name>
    </types>
    <types>
        <members>OldValidationRule</members>
        <name>ValidationRule</name>
    </types>
</Package>

Member names must use the same format as they appear in package.xml — for child metadata types like CustomField, the format is ParentObject.FieldName.

sf CLI Flags for Destructive Deployments

The sf project deploy start command (Salesforce CLI v2) exposes two flags:

• --pre-destructive-changes <path> — points to a destructiveChangesPre.xml file to process before deploying the --manifest.
• --post-destructive-changes <path> — points to a destructiveChangesPost.xml file to process after deploying the --manifest.

Example using pre-destructive:

sf project deploy start \
  --manifest package.xml \
  --pre-destructive-changes destructiveChangesPre.xml \
  --target-org myOrgAlias

The --manifest flag is required even when the package.xml contains no components to add; in that case use an API-version-only manifest.

Components That Cannot Be Deleted via API

The following component types cannot be deleted through any destructive manifest and require manual removal in Setup:

• Record Types — must be deactivated and removed manually.
• Picklist values — field values on picklist/multi-select picklist fields cannot be removed via API. Use the Replace Picklist Values feature or manual field editing.
• Active Flow versions — an active version of an Autolaunched or Screen Flow cannot be deleted via deployment. Deactivate the flow in Setup first, then delete.

Attempting to delete these via a manifest results in a deployment error. The error message is not always obvious about the root cause.

Common Patterns

Pattern 1 — Delete a standalone component with no inbound references

When to use: Removing a custom object, Apex class, Lightning Web Component, or custom metadata type that has no active references in other deployed components.

How it works:

1. Confirm zero inbound references using Setup dependency tooling or sf project retrieve start to inspect local source.
2. Build destructiveChanges.xml listing the component.
3. Create an empty companion package.xml containing only the API version.
4. Deploy using sf project deploy start --manifest package.xml --pre-destructive-changes destructiveChanges.xml --target-org alias.

Why not the alternative: Deploying without an empty package.xml companion will cause a deployment error — the Metadata API requires a valid package manifest in the deployment container.

Pattern 2 — Delete a component that is still referenced (use Post variant)

When to use: Removing a custom field or class that is still referenced by another component, where the referencing component is also being updated in the same deployment to remove the reference.

How it works:

1. Build the updated referencing component (e.g., updated Apex class with reference removed, updated validation rule formula, updated page layout).
2. Include the updated component in package.xml.
3. Place the deletion in destructiveChangesPost.xml.
4. Deploy: the updated component lands first (clearing the reference), then the deletion fires.

sf project deploy start \
  --manifest package.xml \
  --post-destructive-changes destructiveChangesPost.xml \
  --target-org alias

Why not the alternative: Using destructiveChangesPre.xml or plain destructiveChanges.xml in this scenario causes the deletion to fire before the reference is cleared, producing a deployment failure.

Pattern 3 — Troubleshooting a failing destructive deployment

When to use: A destructive deployment is failing and the error is not immediately clear.

How it works:

1. Read the deployment error message carefully. Common patterns: "Component in use by...", "Cannot delete...", "Component not found".
2. "Component in use" — find the referencing component and either update it first (use post variant) or remove the reference in a prior deployment.
3. "Cannot delete" on Record Type, Picklist value, or active Flow — these are undeletable via API; handle manually.
4. "Component not found" — the API name or type is wrong in the manifest; re-check exact casing and type name.
5. Run the checker script: python3 scripts/check_destructive.py --manifest-dir <path>.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Inventory components to delete — List every component by exact metadata type and API name. Confirm no wildcards are being used (they are not supported in destructive manifests).
2. Check dependencies — For each component, determine whether any other active component references it. Use Setup dependency tooling, org-wide metadata retrieval, or sf project retrieve start to inspect locally.
3. Choose the correct manifest variant — Use destructiveChangesPost.xml if the referencing component is being updated in the same deployment. Use destructiveChangesPre.xml or destructiveChanges.xml for standalone deletions. Never attempt to delete Record Types, Picklist values, or active Flow versions via manifest.
4. Build the manifest — Author the XML with correct <types> and <members> entries. Do not include a <version> element. Pair with a valid companion package.xml (even if empty of components, it must specify the API version).
5. Run the checker script — Execute python3 scripts/check_destructive.py --manifest-dir <path> to surface common authoring mistakes before deploying.
6. Deploy and validate — Run sf project deploy start with the appropriate flag. Check the deployment status output. If errors occur, map them to the known failure modes in Pattern 3.
7. Verify deletion in target org — Confirm the component no longer appears in Setup or metadata retrieval. Check that no unexpected cascading deletions occurred.

Review Checklist

Run through these before marking work in this area complete:

• Every component in the manifest is listed by exact API name with no wildcards
• Manifest variant (pre/post/plain) matches the dependency ordering requirement
• No undeletable component types (Record Types, Picklist values, active Flows) are in the manifest
• A valid companion package.xml is included in the deployment container
• The correct sf CLI flag (--pre-destructive-changes or --post-destructive-changes) is used
• Checker script was run and returned no issues
• Deletion confirmed in target org after deployment

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Wildcards silently fail — Unlike package.xml, wildcards (*) in a destructive manifest do not delete all components of a type. The wildcard is treated as a literal member name and the deployment will either fail or silently skip the deletion. List every member explicitly.
2. Post manifest required even when both changes are in the same deploy — Practitioners often assume that listing both the deletion and the updated referencing component in the same deployment is sufficient regardless of manifest type. The pre/plain variant fires the deletion first, before the updated component lands, causing the "still referenced" error even though the fix is in the same package.
3. Deleted components may be re-created by a subsequent retrieve — If a team member runs sf project retrieve start after the deletion without updating their local source, the deleted component re-appears in the local project and may be re-deployed in the next push, undoing the deletion in the org.

Output Artifacts

Related Skills

• metadata-api-and-package-xml — use for package.xml authoring, metadata type reference, and retrieval patterns; the destructive manifest schema mirrors this skill's package manifest structure
• change-set-deployment — use for UI-driven deployment workflows; change sets do not support destructive changes natively