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.
The security token has expired or access to the org has been revoked
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.
How to re-authorize the org connection in Gearset
Navigate to the Salesforce orgs page, find your org in the My org connections tab, and re-authorize the org(s) before trying the comparison again.
Note: You will need to click on the arrow icon 
on the right-hand side to see the 
option, depending on whether your org is a Dev Hub or not.
What to do if you're not the owner of the org connection?
If you are not the owner of the org, and the org connection has been shared with you through Gearset's team features (and it shows in the Connections shared with me tab), the button won't be visible to you!
You will have to ask the owner of the org to re-authorize the connection on their Gearset account before you re-attempt to use the org, e.g. for running a comparison.
Below is an example of what you'd normally see on the Connections shared with me tab:
How to re-authorize a Dev hub org in Gearset
Your Sandbox was refreshed and org connections requires re-authorization
It is an expected behaviour that after Sandbox refresh, Gearset would require you to re-authorize in our app the org (Sandbox) that was refreshed.
You can find out more about this from our documentation:
The org isn't being shown as authorized in Gearset after completing the Salesforce authentication process
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.
A Salesforce org that was shared with you is no longer visible
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.
Salesforce org IP restrictions are in place
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 used to connect to the org doesn't have sufficient permissions
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.
Error communicating with Salesforce during a comparison
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.
Unknown Exception error(s) reported from Salesforce during comparison
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.
The API request limit was exceeded
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.
Connected apps authentication has been blocked
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.
Still having issues?
Contact our team and we'll be happy to help. See how.