Skip to main content

Scan Fails Immediately

If a scan transitions to Failed status within seconds of being started, the issue is almost always related to authentication or Salesforce org configuration rather than the scan itself.

Step-by-step diagnosis​

1. JWT token cannot be generated​

aprity authenticates to your Salesforce org using JWT Bearer tokens. If the token cannot be generated or verified, the scan fails before any metadata is retrieved.

How to verify:

  • In the aprity app, go to Settings > Connection and click Test Connection.
  • If the connection test fails, the scan failure is caused by JWT authentication.

Solution:

2. Connected App is disabled​

The aprity Connected App in your Salesforce org may have been disabled by an administrator.

How to verify:

  • In Salesforce, go to Setup > App Manager.
  • Locate the aprity Connected App and confirm its status is active.

Solution:

  • Re-enable the Connected App and wait 2-10 minutes for the change to propagate before retrying the scan.

3. Salesforce API limits exceeded​

Every Salesforce org has a daily limit on the number of API calls. If your org has already consumed its API allocation, aprity cannot retrieve metadata.

How to verify:

  • In Salesforce, go to Setup > System Overview or Setup > Company Information.
  • Check the API Requests, Last 24 Hours counter against your org's limit.

Solution:

  • Wait for the 24-hour API limit to reset (limits reset on a rolling 24-hour basis).
  • Consider scheduling aprity scans during off-peak hours when other integrations consume fewer API calls.
  • If you consistently hit API limits, contact Salesforce to increase your allocation.
tip

aprity is designed to minimize API consumption by batching metadata requests. A typical scan consumes between 200 and 1,000 API calls depending on org size.

4. Org permissions changed​

If the integration user's profile or permission set has been modified after the initial setup, the user may no longer have the permissions required to read metadata.

How to verify:

  • Confirm the integration user has the aprity User or aprity Admin permission set assigned.
  • Confirm the integration user's profile includes API Enabled and View Setup and Configuration permissions.

Solution:

  • Reassign the correct permission set to the integration user.
  • If the user's profile was changed, restore the required permissions or switch to a profile that includes them.

5. Salesforce org is unavailable​

Salesforce maintenance windows or service incidents can prevent aprity from connecting.

How to verify:

Solution:

  • Wait for the maintenance or incident to be resolved, then retry the scan.

Reading the error message​

When a scan fails, the aprity app displays an error summary. Common messages and their meanings:

Error messageLikely cause
"Authentication failed" or "Invalid JWT"JWT configuration issue (see cause 1)
"Connected App not found"Connected App disabled or deleted (see cause 2)
"REQUEST_LIMIT_EXCEEDED"API limits exceeded (see cause 3)
"Insufficient privileges"Permission issue (see cause 4)
"Unable to connect"Salesforce unavailable (see cause 5)

Still not working?​

If the scan continues to fail after checking all of the above:

  1. Note the exact error message from the scan details.
  2. Run the Test Connection check and record its result.
  3. Contact support at support@aprity.ai with these details, your Org ID, and the scan ID.