SailPoint IdentityIQ Aggregation Troubleshooting: Complete Error Guide

da0105f6.webp
alt: "SailPoint IdentityIQ Aggregation Troubleshooting: Complete Error Guide"

relative: false

Account Aggregation is the task type every SailPoint IdentityIQ deployment runs the most and debugs the least confidently, because a failure can originate in three different layers — the source system, the connector, or IdentityIQ's own correlation logic — and the TaskResult error message rarely tells you which one. This guide walks through the failure modes in the order you should actually check them, with the exact iiq console commands to isolate the cause.

If you're new to IdentityIQ's rule and workflow model, start with our BeanShell Rules, Workflows, and Tasks guide — Correlation Rules and provisioning rules both come up repeatedly below. For the database and scripting side of diagnosing a stuck task from outside the UI, see Java, MySQL, and Shell Scripting for IdentityIQ.

Clone the companion repo: The diagnostic iiq console command sequences, the read-only spt_ health-check queries, and the correlation-rule debug template covered below are all in IAMDevBox/sailpoint-iiq-devtools.

How Account Aggregation Actually Works

Before debugging a failure, it helps to know what the task is doing under the hood. Account Aggregation scans a configured Application, calls the connector to iterate every account (and optionally every group) on that source, and for each account either:

1. Matches it to an existing Link and updates that Link's attributes if anything changed
2. Runs the Correlation Rule to try to match the account to an existing Identity and creates a new Link
3. Creates a brand-new Identity cube, if "Create new identity" processing is enabled
4. Marks the account for one of eight TaskResult actions: Correlate Manual, Maintain, New Account, Reassign, Create New Identity, Ignore, or Remove Account

Each of those actions gets logged per-account in the TaskResult, which is why the first place to look after any aggregation failure is the TaskResult detail screen, not the application server log. The task-level error ("Aggregation failed") is a summary; the per-account errors underneath it are the actual diagnosis.

Failure Mode 1: Connector Exceptions

The most common failure is a ConnectorException thrown while IdentityIQ is trying to iterate accounts or groups from the source. This is a source-system problem, not an IdentityIQ problem, and the fix lives outside IdentityIQ almost every time:

Connector Type	Common Root Cause
LDAP / Active Directory	Bind DN credentials expired or account locked out; search base DN typo; paging cookie exhausted on very large OUs
JDBC / Database	Connection pool exhausted (too many concurrent aggregations against the same source); driver JAR missing after an IdentityIQ upgrade; SQL query in the schema map referencing a column that was renamed
Delimited File	File not present at the configured path at scheduled run time (a nightly export job that hasn't finished yet); encoding mismatch producing malformed rows
Web Services / REST	API rate limiting mid-aggregation on large account populations; OAuth token expired mid-run on a long aggregation with no refresh logic in the connector config

Isolate the connector as the cause before touching anything inside IdentityIQ. From the iiq console:

connectorDebug "Corporate Active Directory" test

This runs the connector's own connection-test method — the same one the "Test Connection" button in the Application configuration UI calls — without running a full aggregation. If test fails, you have your answer immediately and can stop looking at IdentityIQ configuration entirely. If test passes but the full aggregation still fails, move to iterate:

connectorDebug "Corporate Active Directory" iterate

iterate walks the account list the same way aggregation does, which will surface a failure on a specific malformed record (a group membership DN that no longer resolves, an account with a null value in a required schema attribute) that a simple connection test won't catch.

Failure Mode 2: Correlation Failures

If the connector is healthy and accounts are coming through, the next most common failure is correlation: the account exists, IdentityIQ read it successfully, but it can't be attached to an Identity.

"Unable to correlate account to identity" happens when the Correlation Rule for the Application evaluates to no match. Two root causes account for nearly all of these:

• Attribute format mismatch. The most frequent case is an employeeId or similar join key that's formatted differently between the authoritative HR source and the target application — leading zeros stripped, a prefix added, case sensitivity in a string comparison. Check the actual attribute values on both sides, not just the rule logic.
• Aggregation ordering. If this is a new application and the accounts belong to people who don't have Identity cubes yet, correlation will fail on every account because there's nothing to correlate against. Authoritative sources (typically HR/HRIS) must aggregate first to create the Identity cubes; downstream application aggregations correlate against those cubes afterward.

If accounts are correlating to the wrong identity rather than failing outright, that's a Correlation Rule precision problem, not a failure — but it's worth checking the rule's match logic for anything doing a broad LIKE or a first-name/last-name match without a unique secondary key, since those produce false-positive correlations that are far more damaging than an aggregation that simply stops.

Failure Mode 3: Terminated and Orphaned Tasks

A task that shows Terminated rather than an error usually means one of two things:

1. Someone (or a scheduled job overlap) explicitly stopped it — check for a terminate <TaskResultName> call in the audit log or scheduler history.
2. The "Terminate when maximum number of errors is exceeded" threshold was hit. This is a deliberate circuit breaker: rather than aggregating 50,000 accounts and burying one root cause under 4,000 nearly-identical connector errors, IdentityIQ stops after the configured "Maximum errors before termination" count. Read the accumulated errors in the TaskResult before raising the threshold — in the overwhelming majority of cases, all of them trace back to the same upstream problem from Failure Mode 1.

Orphaned task results are a different, purely operational problem: an application server restart, forced shutdown, or crash during a running aggregation leaves the TaskResult stuck in a non-terminal state, even though nothing is actually still running. IdentityIQ won't let you cleanly restart a task while its previous TaskResult still looks "in progress." Clear it from the iiq console:

terminateOrphans please

The please argument isn't decorative — this command force-completes every pending TaskResult it finds as Terminated, so it's built to resist being run accidentally. Only run it when you've confirmed (via the app server process list, not just the UI) that nothing is actually executing.

Once the orphaned result is cleared, restart the task itself:

restart <TaskResultName>

Failure Mode 4: Hung Tasks

A task that neither completes nor errors — it just sits at "running" indefinitely — is the hardest of the four to diagnose because there's no error message to read. Work through it in this order:

1. Confirm it's actually hung, not just slow. Large LDAP OUs and JDBC sources with millions of rows can legitimately take hours. Check the account-processed counter in the TaskResult; if it's climbing, even slowly, it isn't hung.
2. Rule out a connector-level block. Run connectorDebug <applicationName> test in a separate console session while the task is still running. If the test hangs too, the source system itself is unresponsive — a TCP-level connection that was accepted but is never answering (common with an LDAP server behind a load balancer with a stale health check), not an IdentityIQ problem.
3. For partitioned aggregations, one partition thread can silently die while others continue, making the overall task look alive but permanently incomplete. Use:

sendCommand <TaskResultName> stack

This dumps a thread stack trace for the running task into the server log, letting you see exactly which method each partition thread is blocked in — a JDBC Statement.executeQuery call with no timeout is the single most common culprit here.

1. If a partition or the whole task is confirmed dead with no way to recover it cleanly, terminate <TaskResultName> stops it, then follow the orphaned-task cleanup above before rerunning.

Reading the TaskResult Systematically

When triaging an aggregation failure, pull the TaskResult in this order rather than scrolling the raw log top to bottom:

1. Summary counts — accounts scanned vs. accounts with errors vs. accounts correlated. A 2% error rate against one connector points to bad data on specific records; a 100% error rate from the first account onward points to a connection or credential problem.
2. The first error, not the last. Cascading failures (a connection pool exhausted by account 40 will throw the same exception for every subsequent account) mean the last error in a long list is rarely the root cause — it's a symptom of the first one.
3. Per-account action distribution — a spike in "Create New Identity" when you expected "Maintain" usually means a Correlation Rule regression, not an aggregation bug.

Verified Console Commands Reference

Every command below is confirmed against the official IdentityIQ Console documentation, not inferred from behavior:

Command	Purpose
run <taskName> [trace] [profile] [sync]	Runs a task with no arguments; trace prints console output, profile adds timing stats, sync runs in the foreground
runTaskWithArguments <taskName> [arg1=val1,arg2=val2,...]	Runs a task that requires arguments; always executes synchronously
restart <TaskResultName>	Relaunches a previously failed task, in background mode where possible
terminate <TaskResultName>	Stops a running background task; the result shows Cancelled
terminateOrphans please	Force-completes all pending/stuck TaskResults as Terminated
sendCommand <TaskResultName> <command>	Sends an out-of-band command (terminate, reanimate, stack, or connector-specific) to a running or crashed partitioned task
connectorDebug <applicationName> test	Runs the connector's connection test in isolation, without a full aggregation
connectorDebug <applicationName> iterate	Walks the account/group iterator the same way aggregation does, surfacing malformed-record errors
tasks	Lists Name, State, Next Execution, and Cron String for every scheduled task

Enabling Debug Logging for a Specific Aggregation

Rather than raising the global log level (which floods the log with unrelated noise), scope debug logging to the aggregation executor class in log4j2.properties under WEB-INF/classes/:

logger.aggregation.name = sailpoint.api.Aggregator
logger.aggregation.level = debug

IdentityIQ picks up log4j2.properties changes automatically within about a minute — no application server restart required. Remove or comment out the logger once you've captured what you need; aggregation debug logging at scale on a large source is verbose enough to fill a log partition on a multi-hour run.

Preventing Repeat Failures

Once you've fixed the immediate cause, two configuration changes reduce how often you have to do this again:

• Enable Delta Aggregation where the connector supports it. Scanning only changed accounts instead of the full population shrinks both the blast radius and the runtime of any future connector hiccup.
• Set "Disable optimization of unchanged accounts" deliberately, not by default. It forces a full re-read of every account on every run, which is useful for a one-time data integrity check after a bad aggregation, but leaving it on permanently multiplies connector load and increases the odds of hitting exactly the timeout and rate-limit failures described above.

For the underlying rule and workflow mechanics referenced throughout this guide — Correlation Rules, custom TaskExecutors, and the SailPointContext API — see the BeanShell Rules, Workflows, and Tasks guide. For automating the console commands above into a scheduled health check rather than running them manually after every failure, see Java, MySQL, and Shell Scripting for IdentityIQ.