Errors connecting to your Salesforce org(s) or failures when a comparison is in progress are typically caused by either authentication issues, Salesforce limits, or your Salesforce org settings. Errors encountered may be caused by an issue with one or both of your orgs, so be sure to check both source and target org settings.

If you are unable to connect to a Salesforce org you previously successfully authorized, it may be caused by an expired or revoked OAuth security token. To fix either of these issues, you'll need to re-authorize the org in Gearset. Visit the Salesforce orgs page, found under My connections, and re-authorize the org(s) before trying the comparison again. (Note: you will need to click either the cog or the arrow icon on the right-hand side to see the Re-authorize option, depending on whether your org is a Dev Hub or not.)

Note: If you are not the owner of the org, and it has been shared with you through Gearset's team features, the re-authorize button won't be visible. You will have to ask the owner of the org to re-authorize it before trying the comparison again.

If, after completing the org authorization flow, you're taken back to Gearset but the orange tick mark doesn't appear in the username field, you may be hitting an issue with the OAuth authentication process. There can be occasional authentication issues if you're already logged into different Salesforce accounts in your browser when attempting to authenticate an org. This can be resolved by opening an incognito / private browsing window in your browser, logging back in to Gearset, and authorizing the org again.

If you can no longer see an org that a team member has shared with you, ask the owner of the org that you still have sufficient permissions. The owner will have to give you at least comparison access to the org for it to be visible in your connection list. Org permission levels can be changed via the Delegate org access page in Gearset.

If your org has IP access restrictions enabled, you will need to allow access from Gearset's static IP addresses. If your org or profile doesn't have the IPs allowlisted, you will see this access_denied error message.

You can learn about allowlisting the Gearset IP addresses in this separate support article.

The username that was used to authorize the org requires permission to Modify All Data, or the comparison will fail. You can change the permission level via your Salesforce account.

A timeout whilst waiting for Salesforce to prepare the metadata for downloading can sometimes occur during the comparison stage, and will cause the comparison to fail. Timeouts can be transient, and your comparison may work if you simply try again. If your orgs are large, you may also want to try customizing your comparison before starting to reduce the number of metadata types you're comparing.

Sometimes there are unexpected errors from Salesforce while we are retrieving metadata from an org. These are typically caused by specific metadata types that the Salesforce Metadata API has trouble retrieving. The most common examples are with error code (-673032061) which is regarding the Document and/or Email Template metadata types. Removing these metadata types will resolve the error and allow the comparison to finish retrieving the desired metadata.

When comparing very large Salesforce orgs, you may exceed the permissible number of API requests allowed by Salesforce for your org. See the Salesforce knowledge base for more information. We recommend customizing your comparison to reduce the amount of metadata being compared to prevent exceeding the API limit request.

For each of the orgs that you're trying to compare (the source and the target), go to Salesforce and log in to those orgs. From there, go to Manage apps > Connected Apps OAuth Usage. Make sure that OAuth access isn't currently set to block.

Contact our team and we'll be happy to help. See how.