Diagnosing Source Connection Failures
Key Takeaways
Identify the connector variant and failed operation before choosing a diagnostic path.
Differentiate a target timeout, credential rejection and rate-limit response using the connector’s own evidence.
Inspect a VA-based source’s assigned cluster and connector logs. Use source-level connector logs for supported SaaS sources.
Retry only supported transient errors with the connector’s documented controls, then verify results.
Start with what failed
Record the source, connector variant, operation, and the failure time. Test Connection, account aggregation and provisioning do different work. A simple connection test can pass while a particular query fails, and a readable account can still be inaccessible to a write operation. Use the first operation that clearly failed to pick the evidence to examine.
In the source’s connection or aggregation history, check the specific result and its timestamp. SailPoint’s source status can distinguish loss of VA cluster communication, incomplete setup and a failed account or entitlement file upload. A source waiting for its first aggregation may display a configuration message without having attempted a health check. If several VA-based sources in the same cluster fail at the same time, inspect cluster connectivity before changing each application credential. For a SaaS-based source, inspect its supported source connector logs and its documented endpoint rather than the status of an unrelated VA.
| Observation | First hypothesis to test | Evidence that can distinguish it |
|---|---|---|
| VA-based source loses cluster communication | Assigned VA cluster has a health or egress problem | Source association, cluster/member health, required destination checks |
| Target endpoint never establishes a connection | Host, route, port or name is wrong or unavailable | Connector log and network test from the actual execution path |
| Target rejects a request with HTTP 401 | Operation used invalid or missing authentication | Target response details, configured endpoint and credentials |
| Target returns HTTP 429 on aggregation | The service is limiting requests | Connector retry handling and any documented Retry-After header |
| One account read already functions but a write fails | Connector write support, write enablement, or target permission is missing | Exact failed write status, service account rights and test on a controlled target |
| Flat file import fails before account data appears | Submitted format or template may be wrong | Import error and current source schema or template |
Compare two failures in the same integration
A VA-based Web Services source starts failing moments after an access token rotation. The connector log shows HTTP 401 from the target system at the request endpoint. Because a response arrived, the test should first focus on the configured credential and the endpoint’s authentication requirements. Verify that the new secret is in the correct source or referenced credential provider, and retest. Opening a firewall rule does not address the target’s rejection of the credential it received.
Later, the same connector receives HTTP 429 after a large set of operations runs in a narrow time window. The response is evidence of a rate limit. In the documented Web Services VA connector, aggregation retries respond to the target’s Retry-After behavior. Check the target limits and operation schedule before tuning the documented retry behavior. Treat the connector-specific documentation as the authority for its exact delay and maximum. A limit returned by a downstream service is separate from any rate limit on calls to SailPoint’s own application programming interface (API).
Check the fix end to end
For a suspected route failure, identify the actual host and port from the source configuration and test from the appropriate side of the integration. An engineer’s desktop may connect successfully even when a VA or SaaS connector uses a different route. For a certificate error, inspect the requested hostname and configured trust for that connector rather than replacing a working password. For a repeatable query or data error, reproduce with the smallest representative operation and correct the schema, filter or SQL as applicable. On supported sources, aggregation can retry recognized transient errors or use configured additional error strings. A permanent permission or schema defect will still need correction.
Once the configuration changes, repeat the original operation. Check its result and inspect expected data on both systems where appropriate. Record the working connector variant and precise operation alongside the result. A healthy connection is an intermediate result. A successful target write and the expected post-change access are stronger evidence that the precise failure has been resolved.
See SailPoint’s source health and import status, connector log guidance, Web Services VA error cases, and supported aggregation retry behavior.
Immediately after a token rotation, a VA-based Web Services test reaches the intended target, which replies HTTP 401. What should the engineer verify first?
The identity profile’s priority number
The target authentication settings and the credential actually used by the connector
The group membership schema type
The cluster’s disaster recovery pattern
A source’s connection test succeeds and the accounts aggregate. A supported create operation fails because the target service account cannot insert rows. What isolates this defect?
Re-pair the running VA with the same cluster
Change the source from authoritative to non-authoritative
Increase retry frequency for every aggregation
Verify and correct the operation-specific write permission in the target, then retest the create action
Sections you finish are checked off in the contents.