Scan Stuck in Running State
A scan that stays in the Running state longer than expected can have several causes. In many cases, the scan is still progressing normally. This guide helps you determine whether to wait, retry, or escalate.
Understanding scan duration
Scan duration depends on the size and complexity of your Salesforce org. A scan goes through several phases:
- INIT_SCAN -- Prepares the scan configuration.
- FETCH_METADATA -- Retrieves metadata from your Salesforce org. This is typically the longest phase for large orgs.
- BUILD_DEPENDENCIES -- Computes the dependency graph between components.
- ANALYZE_METADATA -- Uses AI to analyze and explain each component.
- BUILD_DOCUMENTATION -- Generates the final documentation output.
- FINALIZE_SCAN -- Wraps up and marks the scan complete.
For a typical org with 50-100 custom objects and moderate automation, expect a scan to take 15 to 45 minutes. Large enterprise orgs with hundreds of objects and complex automation may take over an hour.
Check the progress percentage
Before assuming a scan is stuck, check the scan progress in the aprity app:
- Go to the Analyses tab.
- Locate your scan and check the progress percentage.
- If the percentage is increasing (even slowly), the scan is still running normally.
A scan that shows progress at 0% for more than 10 minutes or whose percentage has not changed in 30 minutes may be genuinely stuck.
Common causes
Backend processing a large org
Large Salesforce orgs with extensive metadata (hundreds of custom objects, thousands of fields, complex automation chains) require significant processing time. The FETCH_METADATA and ANALYZE_METADATA phases scale with org complexity.
What to do: Wait. If progress is advancing, the scan will complete. Monitor the progress percentage periodically.
Worker scaled down mid-scan
The aprity backend runs on Azure Container Apps, which can scale to zero during periods of low activity. If a scale-down event occurs while a scan is in progress, the scan may stall until the worker restarts and resumes processing.
What to do: The system is designed to detect and recover from this scenario automatically. The worker will re-acquire the scan and continue from where it left off. Allow up to 15 minutes for automatic recovery.
Network timeout between services
Temporary network issues between the aprity backend and your Salesforce org can cause individual metadata retrieval steps to time out. The system retries these operations automatically, but persistent network problems can slow down or stall a scan.
What to do: Check if your Salesforce org is experiencing any service disruptions at status.salesforce.com. If Salesforce services are healthy, wait for the automatic retry mechanism to resolve the issue.
When to wait vs. when to act
| Scenario | Action |
|---|---|
| Progress percentage is increasing | Wait for the scan to complete. |
| Progress stalled for less than 30 minutes | Wait. Temporary pauses can occur between phases. |
| Progress stalled for 30-60 minutes | Check Salesforce service status. If healthy, continue waiting. |
| Progress stalled for more than 60 minutes | Contact support. |
Retrying a scan
If you determine the scan is stuck:
- You can start a new scan from the aprity app. The stuck scan will eventually time out and be marked as failed.
- Org administrators can also access the admin panel to manually retry failed scans.
Do not start multiple concurrent scans for the same org. Wait for the current scan to either complete or be confirmed as stuck before starting a new one.
Still not working?
If a scan remains stuck for more than 60 minutes with no progress:
- Note the scan ID (visible in the scan details).
- Record the last known progress percentage and phase.
- Contact support at support@aprity.ai with these details and your Salesforce Org ID.