Skip to main content

Resolving validation errors – "exceeded the allowed number of fields to track on a given entity"

Cause and solution to this Salesforce validation error surfaced on Custom field metadata

Written by Mateusz Kochanowicz

Error overview

This validation error is returned directly by Salesforce during a validation, typically against the CustomField metadata type.

An example of the error message in our app:

"exceeded the allowed number of fields to track on a given entity"

This error usually points to a specific field, e.g. on the above screenshot it's a field named Contact.<xxx>__c.

Explanation of the error

This error indicates that the object the field belongs to (in the example above, it's the Contact object) already has Field History Tracking enabled on the maximum number of fields Salesforce allows, and the field(s) being deployed would be exceeding that limit.

Note: Field History Tracking limits are set per object, not per field (as per Salesforce's documentation), so the specific field named in the error is just the one that exceeded the object's limit - it isn't necessarily the field causing the underlying issue.

Salesforce's default limits are:

  • 20 fields per Standard or Custom object.

  • 6 fields for the Task and Event (Activity) objects.

  • 60 fields maximum limit per object if your org has purchased the Field Audit Trail add-on.

Because the limit applies to the whole object, this error most often appears when:

  • The target org already has hit the limit of 20 fields tracked on that object, and the incoming deployment adds one more.

Also, consider that different orgs selected as target environments of your deployment may have different Field Audit Trail licences. For example, Prod org may have Field Audit Trail add-on purchased, while Sandboxes may remain capped at 20 tracked fields per Standard or Custom object - this may lead to the error showing up on validations against specific orgs to which you team regularly deploys.

Resolution

Follow these steps for further troubleshooting:

  • In Salesforce Setup in the target org, go to Object Manager and select the object named in the error (for this scenario it is Contact object).

  • Open Fields & Relationships, then click Set History Tracking (this may also be shown as Track Field History depending on your Salesforce org).

  • Review the list of fields that currently have tracking enabled. If you're at the limit or have already exceeded t, untick history tracking for any fields your team no longer needs to track, then click Save.

  • Re-run the deployment in Gearset

    • For PRs open in Gearset Pipeline, you can simply re-run their validation.

If every currently tracked field genuinely needs to stay tracked, an alternative option would be to:

  • Check whether Field Audit Trail is enabled consistently across your orgs. If production has Field Audit Trail (raising the limit to 60) but the Sandbox you're deploying to doesn't, you'll need to either align the Sandbox's field tracking allowance with Production (Match Production Licenses to Sandbox tool can help with that), or reduce the number of tracked fields in the Sandbox to bring it under 20.

Keep in mind that the steps above reflect Salesforce's own field history tracking limits and behavior.

Useful resources

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.

Related Articles
Did this answer your question?