Why does a scan hang or fail to complete?

From the "Frontend" console/UI perspective

For Spirion Sensitive Data Platform v13+, the possible reasons a scan can fail usually fall into a few layers:

Executive Summary

A scan can fail for a number of resons.

Some of the most common reasons are as follows:

1. The scan was not configured with the right prerequisites
2. The Agent(s) running the scan was not healthy or not assigned correctly when the scan executed
3. The Targets the scan was configured with could not be accessed (as configured) when the scan was executed
4. The scan scope/playbook/data-type logic did not match what you intended
5. The Agent encountered local execution/resource problems
6. The downstream results pipeline delayed or hid the results

Failure Classes

Important distinctions to note when analyzing the cause of the failed scan:

• Scan failed to start
• Scan started but the Agent did not scan the target
• Scan ran but did not find sensitive data
• Scan found data but the platform did not surface the results (yet)

These are different failure classes.

Agent Requirements were not met

From an Agent perspective, these are explicit prerequisites or behaviors:

• Agents need valid license and registration keys
• Agents must be installed, registered, and available to the Spirion Sensitive Data Platform console
• Agents need an assigned agent policy
• Targets need valid access credentials
• Admins should configure global classifications and global data types

The normal flow is as follows:

1. Create/run discovery scan
2. Review results
3. Configure scan playbook
4. Run the sensitive data scan

Other factors:

• Agent state matters: Scanning, Updating, Monitoring, Idle, Offline
• Agent health is reflected by Agent Last Heartbeat
• Temp-file behavior matters, and the temp location must be a Windows path, not a mapped network drive
• Compressed-file processing depends on temp-file usage
• Spirion Sensitive Data Platform can show unscanned Targets for a given data type

Likely reasons a scan fails or Agents do not scan as configured

1. Agent is not actually available to do the work

• Possible reasons:
• • Agent is in "Offline" status
  • Agent is stuck in "Updating" status
  • Agent never registered with the Spirion console correctly
  • Agent heartbeat is stale, so the platform "sees it" as unavailable
  • The Target has no Agent installed where one was expected
  • Wrong policy was assigned to the Agent
  • Agent was removed, mis-tagged, or not included in the intended Target set
• Practical symptom:
• • Scan is created, but nothing meaningful runs on the endpoint

2. Target access is incomplete or invalid

• Possible reasons:
• • Target credentials were never configured
  • Credentials are wrong, expired, or insufficient
  • Account can authenticate but lacks permission to enumerate or read the Target data
  • path/share/site/mailbox/database exists but the Agent’s execution context cannot reach it
  • Target is present in inventory but not truly accessible from that agent
  • Target-specific auth flow fails or hangs
• Practical symptom:
• • Scan starts, but target remains unscanned or partially scanned
  • Agent may enumerate little or nothing
  • Results may show no findings because the content was never actually read

3. Scan was configured with the wrong scope

• Possible reasons:
• • Wrong Targets or Tags were selected when the scan was created and configured
  • The intended data types were not included
  • Classifications/playbook rules exclude the content you expected
  • file-type filters are too narrow
  • Advanced file identification settings exclude relevant files
  • A Discovery scan was expected, but a Sensitive data scan was run instead
  • Sensitive data scan results were expected, but the discovery results/playbook were not used correctly
• Practical symptom:
• • Scan “succeeds,” but the wrong content was searched
  • Expected sensitive data is missed because it was outside the configured scope of the scan

4. The Target is marked or treated as unscanned for that data type

• Possible reasons:
• • That target/data-type combination was never actually included
  • Scan inheritance, Tags, or targeting rules excluded it
  • Policy/playbook logic caused it not to be processed for that data type
• Practical symptom:
• • The Asset or Target exists in the system, but not for the specific data type you expected

5. Local Agent execution/resource problems

• Possible reasons:
• • temp-file location is invalid
  • temp-file location is a mapped drive instead of a valid Windows path
  • Insufficient local disk space for decompression/temp processing
  • Compressed content cannot be processed correctly
  • The endpoint has local permission issues affecting the scanning backend
  • Local queue/backend initialization fails
• Known operational pattern worth calling out:
• • A local backend/queue permission problem can cause the agent to receive work but never progress into real searching, leaving effective searched locations at zero
• Practical symptom:
• • Scan appears assigned and started
  • Agent may log task receipt
  • Little or no actual scanning happens

6. Policy problems

• Possible reasons:
• • No policy assigned
  • Wrong policy assigned
  • Policy disables or constrains the behavior you expected
  • Watcher policy vs scan policy confusion
  • Policy excludes locations, file types, or behaviors you expected to be included
• Practical symptom:
• • Scan behavior is inconsistent with the intended design even though the agent is healthy

7. Data types or detection logic do not match the real data

• Possible reasons:
• • Expected sensitive data does not match the selected built-in data types
  • Custom data types or regexes are missing or wrong
  • Content format prevents extraction
  • Only metadata was collected, not content analysis
  • file-name / hash / metadata settings were used, but content inspection was needed
• Practical symptom:
• • The target is scanned, but the platform finds no sensitive data even though a human expects it should

8. Discovery vs sensitive-data scan confusion

• This is a frequent reasoning error.

In Spirion Sensitive Data Platform, the normal operating flow is as follows:

1. Discovery scan
2. Review results
3. Build/refine scan playbook
4. Sensitive-data scan

• Possible failure mode:
• • The admin expects full sensitive-data findings from a discovery-oriented setup
  • or expects a refined sensitive-data result without first using discovery results to tune the playbook
• Practical symptom:
• • Scan outcome is “working as configured,” but not “working as intended”

9. Target-specific protocol or service issues

• Possible reasons:
• • SharePoint / cloud / database / Exchange / website target has its own auth or connectivity issue
  • Required service endpoint is unreachable
  • Protocol behavior changed or the auth model is no longer accepted
  • Some target failures may hang rather than fail cleanly
• Known pattern:
• • Some SharePoint basic-auth failures can hang instead of producing a fast clean failure
• Practical symptom:
• • Some targets never finish properly, or finish with missing coverage

10. Results-pipeline or visibility problems after scanning

A scan can appear to have failed even when the endpoint did search.

• Possible reasons:
• • Results were not shipped from the Agent
  • Ingress accepted poorly or not at all
  • Kafka backlog delayed processing
  • SearchPersistence is lagging or failing
  • Import into the platform is delayed or failed
  • UI/search indexes have not caught up yet
• Practical symptom:
• • Endpoint performed work, but results are missing or delayed in the UI

This is especially important because “no visible results” is not the same as “no scan occurred.”

Why Spirion Agents may fail to discover sensitive data, even when scanning successfully

If the Spirion Agent(s) scanned as intended, but still did not discover the sensitive data you expected, some common reasons are as follows:

• Wrong data types (SSN, credit card numbers, phone numbers, etc.) were scanned (wrong scan configuration)
• Wrong data classifications were set
• Wrong playbook was set when configuring the scan
• Wrong file-type inclusion/exclusion was set when configuring the scan
• Content was/is stored in a format the scan did not inspect (wrong scan configuration)
• Permissions allowed listing content but not reading the content
• The data lives in locations excluded by the policy the scan was configured to use
• The Target/data-type combination was not actually scanned (wrong scan configuration)
• The scan was discovery/metadata-focused rather than content-focused (wrong type of scan was executed: discovery scan instead of a sensitive data scan)
• Results were found but did not persist or surface

A practical diagnostic model

The cleanest way to troubleshoot is by layer:

A. Did the scan save and start?

Confirm the following:

• The scan exists
• The intended Targets of the scan are set in the scan configuration
• The intended playbook/data types (SSN, credit card numbers, etc.) of the scan are set in the scan configuration

B. Did the right Agent pick it up?

Check the following:

• Agent status
• Recent Agent heartbeat
• Policy assignment
• Target/Agent association

C. Could the Agent access the Target?

Ensrue the Target is correctly configured in Spirion Sensitive Data Platform. Check the following:

• Credentials used to access the Target
• Permissions to the Target content
• Path/site/mailbox/database reachability

D. Did the agent actually process content?

Check the following:

• Local temp path
• Local disk/resource issues
• Compressed-file handling
• Local backend/queue issues

E. Did the configuration match the requested detection?

Check the following:

• Data types
• Classifications
• File filters
• Playbook logic
• Scanned vs unscanned target status per data type

F. Were results shipped and surfaced?

Check the following:

• Shipping/ingestion/persistence/UI delay

Short answer

The most common root causes are typically as follows:

• Offline or unhealthy (stale, misconfigured, etc.) Agents
• Missing/wrong Target credentials
• Wrong policy/playbook/data-type configuration
• The Target is not included for that data type
• Local temp-path/resource/backend issues on the endpoint
• Results-pipeline delays or failures after the scan

From a Backend Perspective

The following are the possible backend reasons why scan Agents fail to scan Targets or discover sensitive data, organized by the pipeline stage where the failure occurs:

• Discovery Stage
• Job Queue / Connectivity
• Search / Scanning Stage
• Results Delivery (Shipper Stage)
• Server-Side Ingestion
• Configuration Errors
• Diagnostic Approach

Discovery Stage

• The Discovery Agent fails to identify targets or locations, so the job queue (the "to-do list" for the scan) is never created.
• Without a queue, no search agents have anything to act on.

Job Queue / Connectivity

• The job queue is created but search agents never claim the jobs — typically caused by the following:
• • Network/firewall rules blocking Spirion Agents from reaching the discovery endpoint
  • Incorrect port configuration (e.g., using default PostgreSQL/pgBouncer ports 5432/6432 instead of the Spirion defaults 5433/6433)
  • Agents timing out while waiting to connect
• The per-scan job queue table is never created, or is cleaned up prematurely, leaving Agents waiting indefinitely or exiting early

Search / Scanning Stage

• The search agent completes its scan but fails to publish results into the Shipper Queue
• An agent crashes mid-job — the system uses heartbeats to detect stale Agents and re-queue abandoned work, but persistent crashes will still result in incomplete scans (consistent with the "Last Heartbeat" field you saw in the Scan Details pop-up)

Results Delivery (Shipper Stage)

• Results are staged in the Shipper Queue but not delivered to the Ingress Service, due to:
• • The IDFMessagingSvc.exe Shipper Process failing to drain the queue
  • Network connectivity problems preventing posting to Ingress

Server-Side Ingestion

• Even if results are successfully shipped, they may not appear in the UI if:
• • The Ingress Service fails to stream data to Kafka
  • The SearchPersistence service fails to consume from Kafka and write to SQL Server

Configuration Errors

• Misconfigured ports, incorrect connection strings, or other configuration mismatches that prevent Agents from establishing connections at any stage of the pipeline

Diagnostic Approach

To pinpoint the failure, trace the data through the full pipeline:

Discovery → Job Queue → Search → Shipper Queue → Shipper → Ingress → Server Storage

Key logs to check:

• identityfinderCMD.exe — Discovery and Search activity
• IDFMessagingSvc.exe — Shipper activity
• Ingress service logs
• SearchPersistence logs