2026-06-08 · 8 min read
Why Change Sets Fail, and How to Move the Records They Can't
The real reasons change sets are painful: dependencies you add by hand, no rollback, slow validation, no data. What to use for metadata, and what to use for records.
Change Sets are Salesforce's built-in tool for moving customizations between orgs. They're also one of the most frustrating things a Salesforce admin does regularly. Validation fails with an error that doesn't point at the real problem. There is no undo. To fix the change set you clone it and start again. Days pass.
Here's why.
The Change Set Pain Points
Dependencies You Add by Hand
Change Sets have a View/Add Dependencies button, but it doesn't catch everything, and you still pick and add each component yourself. If Custom Object A has a lookup to Custom Object B and you leave B out, validation fails in the target org. Tracking dependencies by hand is fine for five items and painful for fifty.
No Rollback
Once a Change Set deploys, it's done. If something breaks in production, there is no undo button. You build a new change set that reverses the changes, deploy that, and hope nothing else broke.
Slow Validation
Validating a change set in production runs Apex tests, which can take a long time in a large org. The errors you get back don't always point to the real problem. If validation fails, you clone the change set, fix it, upload it again and wait again.
No Diff Against the Target
A change set lists its components, but it doesn't show what each one will change in the target org. You find out what a field or rule looked like before only after it has been overwritten.
Can't Move Data
Change Sets move metadata only. If you need to copy records (accounts, products, price books, reference data), you need Data Loader or another process, and you have to work out the load order and the record IDs yourself.
Clumsy Reuse
Once uploaded, a change set is locked. To change it, you clone it and edit the clone. Keeping several orgs in step means a trail of near-identical change sets.
Easy to Miss Components
In large deployments, it's easy to forget that Custom Field X references Custom Object Y, or that a Validation Rule depends on a Formula Field. Change Sets don't enforce this discipline.
Alternatives for Metadata
Salesforce CLI and Source Format
The modern way to move metadata is the Salesforce CLI (sf), working with source code in Git. You retrieve metadata from an org into a repo, commit it, and deploy it to another org.
It supports more metadata types than Change Sets, and Git shows you exactly what changed. Rolling back means reverting in Git and deploying again, sometimes with a destructive-changes manifest for components you added.
The learning curve is steep if you're not comfortable with Git and the command line. Scratch orgs and packaging also need a Dev Hub. For a one-off deployment, it can feel like overkill.
Unlocked Packages
Unlocked packages bundle and version metadata. You create package versions with the Salesforce CLI against a Dev Hub and install them in other orgs.
The setup takes work: you manage versions and package dependencies. For admins who just need to move a few custom fields, it's a lot of machinery.
Both are standard in mature DevOps teams. Both are a lot to learn for an admin with a weekend deployment window.
The Part None of These Move: Records
Change Sets, the CLI and packages all move metadata. None of them copies records. Seeding a sandbox, promoting reference data, or keeping two orgs' data in step is a separate job, and it is the job SFDC Police's Data Migrator is built for.
Data Migrator copies records between orgs. It does not deploy metadata: the objects and fields must already exist in the target, so move them first with a change set, the CLI or a package. Before a run it compares the two orgs' schemas and checks your permission sets, so you find a missing field before you write anything.
Parent-First Load Order
It orders the objects you pick from their relationships, so parents load before their children, and it remaps lookups between the records it migrates. No hand-built load order.
A Dry Run Before Any Write
Before writing, a dry run shows the record count per object, the order the objects will load in, and the conflicts it can see coming: duplicate external IDs in the target, lookups to records outside the run, and picklist values the target doesn't allow. It also estimates the API calls the run will use. You read it, then decide.
Four Modes
You choose how the target is treated: Seed inserts new records, Promote creates or updates records, Repair updates records that are already there, and Mirror creates or updates records and, for the objects you opt in, deletes target records that aren't in the source.
Matching Between Unrelated Orgs
Related orgs (a production org and its sandbox) can match on record Id. Between unrelated orgs, you choose the key: an external ID field, or a natural key you pick, such as account name plus billing country. When a record already exists in the target but differs, it is reported as drifted, and you choose whether to update it.
Rollback with Before-State Snapshots
Rollback deletes the records a run inserted and patches updated records back to the values it snapshotted before the write. You confirm it before it runs. From version 1.1.13, a lookup patched after the main load is applied only once its original value is snapshotted.
Checkpoint Resume
Progress is saved as the run goes, so a run interrupted by a closed browser can resume from the last checkpoint.
Preflight Checks
Preflight looks for common edge cases, such as encrypted fields, duplicate rules, polymorphic lookups, person accounts and multi-currency, and tells you what each one means for the run.
Which Tool for Which Job
Use Data Migrator if:
- You need to copy records between orgs, in dependency order.
- You want a dry run before writing and a way to roll back.
- You're moving records between unrelated orgs and need to match on your own key.
Use Salesforce CLI if:
- You're in a DevOps team with Git and CI/CD.
- You're deploying metadata from source control.
- You need to version and audit every change.
Use Change Sets if:
- You're moving a small number of components between related orgs and prefer the Setup UI.
Getting Started
See the Data Migrator feature documentation for a step-by-step walkthrough. No setup required: Data Migrator runs on your existing Salesforce session and reads and writes through Salesforce's APIs (REST and Bulk).
For more, read Migrating Orgs Safely or explore the features page.