Salesforce permission set deployment fails most often not because the metadata is wrong, but because it depends on something the deployment forgot to include. A permission set that grants edit access to a custom field will error out if that field is not part of the same deployment or already live in the target org. The fix is not more testing. It is understanding what a permission set actually depends on before you click deploy.
I have watched teams spend two days chasing a failed release, convinced the problem was a broken trigger, when the real culprit was a permission set referencing a field that got renamed three sprints ago. Apex gets the blame. Permission sets quietly cause more re-runs.
Why permission sets break more deployments than code does
Apex classes fail loudly and specifically. The compiler tells you the line number and the missing reference. Permission sets fail with vague errors like "Invalid field" or "insufficient access rights on cross-reference entity," and they rarely point at the actual cause.
The reason is structural. A permission set is not a standalone unit. It is a bundle of pointers into your object model, your field list, your record types, your Apex classes, and your Visualforce pages. Every one of those pointers has to resolve correctly in the target org at deploy time, in the right order, or the whole component fails.
Code dependencies are usually contained within the same metadata type. Permission set dependencies fan out across nearly every other type in your org. That is exactly why they cause more grief per line of XML than any other metadata component.
The field-level security dependency trap
Field-level security entries inside a permission set reference fields by API name. If a field was deleted, renamed, or never deployed to the target org, the permission set deployment fails on that single entry, and Salesforce does not always tell you which one.
This gets worse with formula fields and fields on managed packages. A permission set built against a package version that is not yet installed in the target org will fail silently until someone traces the error back to a missing prerequisite install.
Here is a common sequence that breaks in production but works fine in sandbox: a developer adds a custom field, grants access to it in a permission set, and deploys both together. If the field lands in a metadata batch that runs after the permission set batch, the permission set has nothing to point to and the deployment aborts.
- Field created and permission set updated in the same change set, wrong order
- Formula field references a field on a related object that was not included
- Permission set grants FLS on a package field before the package version is installed
- Field deleted in a cleanup pass but still referenced by an old permission set nobody archived
Object and record type visibility mismatches
Record type visibility settings inside a permission set are just as fragile as field-level security, and they fail for a similar reason: the record type has to exist in the target org, under the same object, before the permission set can grant access to it.
Teams that rename record types or consolidate them during a cleanup project often forget that every permission set referencing the old developer name now points at nothing. The deployment does not warn you in advance. It just fails at the permission set step, several stages after the record type change went in.
Object-level permissions add another wrinkle. A permission set that grants "Modify All" on a custom object requires that object to already exist with the correct sharing model applied. If the object's deployment and the permission set's deployment are split across two change sets, sequencing becomes the entire game.
The missing assignment problem nobody plans for
Deploying a permission set's definition is only half the job. The PermissionSetAssignment records that actually give users access do not move with a standard metadata deployment at all. Change sets and most metadata API deployments push the permission set shell, not who has it.
This creates a specific failure mode: the deployment reports success, QA signs off, and then nobody in production can see the new fields or object because the permission set exists but is assigned to zero users. It is not a deployment error. It is a deployment gap, and it is far more common than actual XML failures.
The workaround most teams use is a post-deploy script or a manual assignment step, which is fine until someone forgets to run it. A cleaner approach treats permission set assignments as their own tracked artifact in the release plan, not an afterthought handled by whoever remembers first.
| What moves automatically | What does not |
|---|---|
| Permission set definition (FLS, object perms, record types) | PermissionSetAssignment records |
| Permission set group definitions | User-to-group assignments |
| Muting permission sets | Which users have the mute applied |
Order of operations: why sequence matters more than content
Two deployments can contain the exact same components and produce different results depending on the order those components get processed. Salesforce's metadata API does attempt automatic dependency resolution for certain types, but permission sets sit in a gray zone where that resolution is inconsistent.
The safest sequence, in practice, looks like this: custom objects and fields first, then record types, then Apex classes and Visualforce pages referenced by the permission set, then the permission set itself, then assignments. Skip a step or reverse two of them and you get a deployment failure that has nothing to do with the code quality of anything involved.
Manually managing this order across a change set with forty components is tedious and error-prone. It is also exactly the kind of problem that does not scale past a two-person admin team, which is why larger orgs end up either over-engineering their release checklists or automating the dependency graph entirely.
How DeployEzee resolves permission set dependencies automatically
DeployEzee builds a dependency graph before it moves a single component. When a permission set references a field, record type, object, or Apex class, the tool checks whether that dependency already exists in the target org or is included in the same deployment package. If it is not, you get a specific warning before deployment, naming the exact missing reference instead of a generic error code after the fact.
Sequencing is handled the same way. DeployEzee orders components automatically based on the dependency graph it built, so fields land before the permission sets that reference them, and record types land before the permission sets that grant visibility to them. You do not have to hand-build a deployment order and hope you remembered every edge case.
For the assignment gap, DeployEzee tracks PermissionSetAssignment records as part of the release package rather than treating them as a separate manual task. That closes the specific failure mode where a permission set deploys clean but nobody actually has access to use it. Sandbox-to-production comparisons run before deploy time flag where target org record types or fields diverge from what the source assumes, which catches the renamed-field and consolidated-record-type problems before they turn into a failed job.
None of this replaces good release hygiene. Archiving unused permission sets and keeping field names stable still matters. But when the dependency graph is checked automatically instead of manually, the failure rate on permission set deployments drops substantially, and the failures that remain come with a reason attached instead of a guess.
Frequently Asked Questions
Why does my Salesforce permission set deployment fail with an invalid field error?
This almost always means the permission set's field-level security entry points to a field that does not exist in the target org yet, or was renamed or deleted. Check whether the field is included in the same deployment package and whether it deploys before the permission set. Managed package fields need the correct package version installed first, which is a common blind spot.
Do permission set assignments move with a metadata deployment?
No. Standard metadata API deployments and change sets move the permission set definition itself, but PermissionSetAssignment records that give specific users access do not come along automatically. Teams typically need a post-deploy script, a manual assignment step, or a deployment tool that tracks assignments as a release artifact.
What order should permission sets deploy in relative to objects and fields?
Custom objects and fields should deploy first, followed by record types, then Apex classes or Visualforce pages the permission set references, then the permission set itself, and finally any assignments. Reversing this order is one of the most common causes of a failed permission set deployment even when every component individually is correct.
Can a permission set deployment succeed but still leave users without access?
Yes, and this is one of the more deceptive failure modes in Salesforce releases. The permission set definition deploys successfully, sign-off happens, and then no user in production actually has it assigned because assignments were never part of the deployment package. It looks like a success on the deployment log but functions as a gap in access.
How does DeployEzee prevent permission set deployment errors?
DeployEzee builds a full dependency graph before deployment, checking every field, object, record type, and class a permission set references against the target org. It sequences components automatically so dependencies land before the permission sets that need them, and it tracks PermissionSetAssignment records as part of the release rather than a separate manual step.