You may see the following error message when comparing with an org:
Could not register <org username>: The total size of the metadata downloaded exceeded Salesforce's limits. Try excluding some metadata types by setting comparison options.
Which looks like this:
This happens because a request to the Salesforce org has exceeded the download retrieval limit of Salesforce's API, which is:
The maximum size of the deployed or retrieved .zip file is 39 MB.
When you request lots of metadata (by that I mean more than what's likely to be over the 39 MB limit), Gearset makes an educated guess to split and batch up the requests, so that ideally each request of metadata type batch is under the limit.
This is what results in a successful comparison containing a lot of metadata.
However, because Gearset doesn't know how big (in terms of MB) each metadata type will be until we try to download it, there is a possibility that the educated guess fails, and the request generates a batch to download that is over 39 MB. This would result in The total size of the metadata downloaded exceeded Salesforce's limits error.
Selecting a different set of metadata type in the request also changes which batch an item is allocated to, which may be just enough to tip it over the limit. So the batching is not deterministic as each metadata item can be widely different in size.
In summary, the Gearset workaround to Salesforce's limits is not guaranteed to always be successful. You may want to change the metadata filter (adding or removing types, i.e. experience tells us to not include all Document metadata type) to work around the error.
If you are unable to reduce amount the metadata types in your metadata comparison filter, please reach out to us via the in-app chat where we will be able to discuss other potential workarounds.