Profile permissions cannot be granted because the user license doesn't include them

A profile deploy fails halfway through your release. The CLI shows Profile permissions cannot be granted because the user license doesn't include them. The profile worked in your sandbox. The exact same XML is now refusing to deploy to production. The team scrambles to figure out which permission, which profile, and what the right fix is, all while the release window is closing.

What the platform is checking

Every user license in Salesforce defines a set of permissions that profiles tied to that license may grant. A Sales Cloud license allows different permissions than a Customer Community license; an Enterprise Edition license allows different permissions than a Professional Edition. When you deploy a profile, the platform validates each permission in the profile XML against the target license's allowed set. Any permission that the license doesn't include triggers Profile permissions cannot be granted because the user license doesn't include them.

The check is per-permission and per-license, not per-org. A sandbox and a production org that have the same edition and the same licenses produce the same validation result. A sandbox with different licenses than production (a common case when production is Enterprise Edition and the sandbox was provisioned from a partial copy with reduced licenses) produces different results, which is why the same XML can succeed in one org and fail in another.

The error message names specific permissions in some cases and stays generic in others. The diagnostic is to compare the profile XML against the target org's license capability set.

The classic broken example

A team builds a custom profile called "Service Manager" in an Enterprise Edition sandbox. The profile grants the ManageCases permission. The deploy ships cleanly. Months later, the team tries to deploy the same profile to a Customer Community license org for a partner-facing portal. The deploy fails:

<Profile xmlns="http://soap.sforce.com/2006/04/metadata">
    <userPermissions>
        <enabled>true</enabled>
        <name>ManageCases</name>
    </userPermissions>
    <!-- ...other permissions... -->
</Profile>

ManageCases is a Sales/Service Cloud feature. Customer Community licenses don't include it. The deploy fails on the first profile permission the target license doesn't allow.

The fix: remove the unsupported permissions

The deploy refuses the entire profile if any permission is unsupported. The fix is to remove the offending permissions from the XML and retry. Two paths:

Manual edit. Open the .profile-meta.xml file, find the named permission, set <enabled>false</enabled> or delete the block entirely. Redeploy.

Profile-aware deploy tooling. Tools like Gearset, Copado, and Flosum have profile-merge features that compare source and target license capabilities and strip incompatible permissions automatically. For teams that deploy across heterogeneous license combinations, the automated path is much faster.

The deeper question is what the profile should grant. If the profile is for community users, it probably shouldn't have ManageCases anyway; the developer who added it was likely confused about the target audience. Use the deploy failure as a prompt to audit the profile's scope.

The fixed example

The same Service Manager profile, scoped to the community license:

<Profile xmlns="http://soap.sforce.com/2006/04/metadata">
    <custom>true</custom>
    <description>Community service manager, limited case visibility</description>
    <userLicense>Customer Community</userLicense>
    <userPermissions>
        <enabled>true</enabled>
        <name>ViewMyTeamsDashboards</name>
    </userPermissions>
    <objectPermissions>
        <allowCreate>true</allowCreate>
        <allowEdit>true</allowEdit>
        <allowRead>true</allowRead>
        <object>Case</object>
    </objectPermissions>
    <!-- No ManageCases user permission -->
</Profile>

The community-license version grants Case object access and edit rights (which the license allows) but omits ManageCases (which it doesn't). The deploy succeeds.

The <userLicense> element in the XML is informational, but tooling sometimes uses it to validate at lint time. Setting it correctly helps catch the mismatch before deploy.

Common permissions that hit this error

Some permissions are reliably absent on community licenses, partner licenses, and other restricted-access licenses. Knowing the recurring offenders shortens the diagnosis:

• ManageCases, ManageContent, ManageBusinessHours: Service Cloud features, absent on community licenses.
• ApiEnabled: not granted on Customer Community Login licenses by default.
• ViewSetup, ManageUsers, AssignPermissionSets: admin-tier permissions, absent on most non-admin licenses.
• EditTask, EditEvent: absent on some community and partner licenses.
• RunFlow: absent on Chatter External licenses.
• BulkApiHardDelete, ManageDataIntegrations: developer/integration permissions, absent on read-only licenses.

The official "User License" pages in Salesforce Help list the included permissions per license. Bookmarking the page for your target licenses lets you check candidate permissions before adding them.

A subtler case: standard versus custom profiles

Standard profiles ("System Administrator", "Standard User", "Marketing User") cannot be edited freely; the platform protects them. If you've cloned a Standard profile and added permissions, the clone might inherit permissions that the platform locks. The deploy then fails not because the license disallows a permission, but because the platform reserves it.

The error message is the same. The fix is different: rebuild the profile from a Permission Set baseline instead of cloning a standard profile.

Permission Sets as the structural fix

The modern Salesforce guidance is to keep profiles minimal and grant most permissions via Permission Sets. The reasons line up with this error class:

• Permission Sets are easier to make license-portable.
• Removing a permission from a Permission Set is reversible; removing it from a profile (and then realizing you needed it) requires careful reasoning about who lost which access.
• Permission Sets stack additively, so you can grant different combinations to different users without proliferating profile clones.

If you're hitting Profile permissions cannot be granted repeatedly, treat it as a signal to refactor toward Permission Sets. The migration is non-trivial (audit every profile, move grants out, assign sets to users) but it pays off for the lifetime of the org.

Audit before deploy

A defensive workflow that catches the error at PR time instead of deploy time:

1. Maintain a list of allowed permissions per license type in a config file.
2. Add a CI step that parses every .profile-meta.xml and cross-references each permission against the license-allowed list.
3. Fail the PR if a profile references a permission its declared license doesn't include.

The script is short (a Python or Node parser that walks the XML and looks up each permission). The benefit is that the error class disappears from your release process. It moves left to PR review, where the cost of fixing is low.

For an org with many profiles, a one-time audit script can also identify "drift" between sandbox and production licenses. Sandboxes refreshed before a license change often have permissions the production license no longer supports. Running the audit on every sandbox refresh catches the drift.

When the same profile XML works in some orgs and not others

The same profile file might deploy cleanly to:

• Production (Enterprise Edition with all Sales Cloud features).
• Full Copy sandbox (matches production).
• Partial Copy sandbox if the sandbox was refreshed from production with all licenses.

And fail in:

• Developer Edition org (smaller license footprint).
• Partial Copy sandbox provisioned with a reduced license set.
• Scratch org with a non-matching edition setting.

The diagnostic is to compare the licenses installed in each org via Setup → Company Information → User Licenses. The list shows every license, its count, and which features it includes. Match against the profile's permissions, and the mismatch becomes obvious.

A long-tail of "vendor permissions"

Managed packages from third-party vendors add their own user permissions, like VendorXCanAccessDashboards or VendorYIntegrationEnabled. If you're deploying a profile that grants these and the target org doesn't have the vendor's package installed, the deploy fails with a variant of the same error.

The fix is the same: either install the package first, or remove the permission from the profile. The error message names the permission's API name, which usually includes the vendor's namespace prefix.

Documenting why a permission is in the profile

A practical habit that prevents recurrence: comment every non-obvious permission in the profile XML with a justification.

<userPermissions>
    <enabled>true</enabled>
    <name>EditTask</name>
    <!-- Required for the Service Manager role to reassign open tasks. Owned by the Service team. -->
</userPermissions>

The comments don't affect deploy behavior, but they tell future maintainers why each permission is there. When a permission has to be removed for a license-portable deploy, you know whether removing it breaks the intended use case.

A note on the validation ordering

The Metadata API validates profile permissions in the order they appear in the XML, but the error message names the first conflict, not all of them. If you fix the named permission and redeploy, you might hit a second conflict on the next deploy attempt. And a third on the one after that.

To find all conflicts in one pass, deploy with sf project deploy validate --target-org X (the validate-only mode) and look at the full result. Some tooling parses every error in the response, not just the first; vanilla CLI shows only the first by default. Add --verbose for fuller output.

For very heavy profiles with dozens of permissions, the iterative deploy-fix-deploy cycle is painful. Use a profile-aware diff tool to compare source profile to target license capability and produce the full list of incompatibilities upfront.

Profile permissions in sandbox refreshes

When a sandbox is refreshed from production, profiles copy over. If the sandbox has fewer license types than production, some profile permissions become orphaned: they're in the profile XML but the target license doesn't support them. The sandbox doesn't immediately surface this as an error; the permissions just don't take effect at runtime.

The trouble surfaces when you later try to deploy that sandbox's profile XML to a different org. The orphaned permissions trigger Profile permissions cannot be granted against the new target's license. The fix is to audit and clean up profiles after every sandbox refresh, removing any permissions the sandbox's licenses don't support.

This is one more reason teams move away from heavy profiles and toward Permission Sets: Permission Sets travel cleaner across sandbox refreshes because they aren't bound to a license at the profile level.

Further reading from Salesforce

• Salesforce Help: User License Types
• Salesforce Help: Profile Permissions
• Salesforce Help: Permission Sets
• Metadata API Developer Guide: Profile
• Trailhead: Profile and Permission Set Management