Error overview
You may come across this Salesforce validation error when deploying a profile to a target Salesforce org.
An example of the validation error in our app on profile metadata:
Cannot update: userLicense
Every Salesforce profile is tied to a single user licence (for example Salesforce or Salesforce Platform) at the moment it's created. Salesforce doesn't allow that licence to be changed afterwards, either in Setup or through the Metadata API.
A profile's metadata includes a userLicense element. If you deploy a profile that already exists in the target org, and the userLicense value in your source is different from the one in the target, Salesforce rejects the change and returns this error.
Explanation of the error
In the cases our support team has investigated, the cause was always same - a profile with the same name existed in both source and target environments, but each environment's profile was tied to a different licence.
A typical example is a profile that uses the Salesforce licence in the target org, while the profile version in the source (e.g. Git branch) uses the Salesforce Platform license.
This can happen even when you think you're deploying a brand new profile. If a profile with the same name was created manually in the target org (or by an earlier deployment) with a different licence, Salesforce treats your deployment as an update to that existing profile.
How to confirm the cause
Open the comparison used for the deployment.
For direct org to org (or Git to org) validation/deployment, find your comparison on the Deployment history page.
For a failed validation of a pull request in a Gearset Pipeline, on your Pipelines UI page, click on the PR and in the
Metadata validationtab under "X Validation failed" notification select View details.For a CI job deployment that errored, navigate to CI jobs page, click the History button (next to your CI job), then Comparison results to view the comparison of the failed run.
Find the profile name referenced in the validation error message, and compare its XML differences (source vs target environment).
Look for the
userLicenseline. If the source and target values differ, this is the cause of the error.Optionally, check in Salesforce under Setup > Profiles, where the User License column shows which licence each profile uses in each org.
Resolution
We suggest one of the approaches below. Which option to choose depends on which license is the correct one for the profile that fails the validation/deployment.
Option 1 - the target org's licence is correct
If the profile in the target is already on the right licence, make the source environment match it.
For a Git-based source (e.g. feature branch), follow these steps:
Update the
userLicensevalue in the profile's XML file directly in your (feature) branch so that it matches the value in the target (org)Commit the change
Re-run the comparison, or re-validate the PR in your Gearset Pipeline.
In some cases, Gearset's conflict resolution for a PR in the pipeline may allow you to resolve the conflict directly in our app. In this case select the version whose userLicense matches the target org (e.g. INT).
Alternatively, Gearset allows you to download the .zip created from your comparison.
Then you can make manual changes to the affected profile’s XML locally, compress the package back into .zip and use the same .zip file as the source of your deployment.
More information on how to do it in our article on how to change the deployment package before deploying.
Option 2 - the licence in the source is correct
Because the licence on an existing profile can’t be changed, you’ll need a new profile in the target org that uses the correct licence:
Give the profile a new name in your source. In a Git branch, rename the profile’s XML file (for example
SalesUser.profile-meta.xmltoSalesUserPlatform.profile-meta.xml) and commit the change. In a source org, clone the profile under a new name; the clone keeps the original profile’s licence.Deploy the renamed profile to the target org. Because no profile with that name exists in the target yet, Salesforce creates it with the licence from your source instead of trying to update the existing one.
Reassign the relevant users to the new profile.
If those users also need a different user licence, check Salesforce’s guidance first. Not every licence change is supported on an existing user, and some changes require a new user record.
Once nothing depends on it, you can retire the old profile.
Confirm the behavior in Workbench
If you'd like to confirm that this is a Salesforce restriction, you can replicate the deployment in Workbench, which uses the same Metadata API as Gearset. Our guide on how to replicate deployment errors with other tools walks through the steps.
Are you installing unlocked packages?
Salesforce has also documented a separate known issue (ref. ID: W-8777449) where the same error appeared while installing unlocked packages in Spring '21 orgs.
That issue is marked as fixed in Spring '21 Patch 6.0. Salesforce's workaround was to set includeProfileUserLicenses to true in the packageDirectories section of sfdx-project.json and upload a new package version.
If, for any reason, you see the error while installing an unlocked package, please refer to Salesforce’s documentation:
Disclaimer: This error is returned by Salesforce directly, rather than Gearset. Even so, we offer guidance based on our combined experience with the Metadata API. Where possible, we try to help guide you to fix or avoid this error. In the case that this isn't possible, we may need to direct you to Salesforce support for further clarification.