Error overview
Based on Salesforce documentation, you may come across this validation error when you're deploying Role metadata type, or when your deployment package contains Role metadata components.
An example of a returned error message is:
"field integrity exception: unknown - (<xxx> Access level below organization default)"
<xxx> in this context would reference a specific Custom object metadata, such as Case or Opportunity.
Explanation of the error
This error is likely to surface when the Organization-Wide Defaults (OWDs) differ between the source and target orgs.
For example, the access levels for Opportunities and Cases depend on these Organization-Wide Defaults settings.
If the source org has Cases set to 'Private', but the target is set to 'Public Read/Write/Transfer,' the role details in your deployment package can't be applied correctly in the target org - therefore validation fails with this Salesforce error.
Resolution
To fix this issue, prior to the deployment in our app, make sure that the Sharing Settings for the object in the target org match those in the source org.
If this condition is met, your validation should be successful.
More information on this error can be found in:
Salesforce Known Issues (Published 3 Feb 2021)
Disclaimer: This error is returned directly by Salesforce, 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.