SailPoint IIQ Troubleshooting: A Step-by-Step Guide for Common Issues

What is SailPoint IIQ troubleshooting?

SailPoint IIQ troubleshooting is the structured process of finding why an IdentityIQ operation did not produce the expected result, proving the cause with evidence from task results, Syslog, log files and object XML, and then applying the smallest safe fix. It is a daily duty for IIQ support engineers, administrators and developers.

Most IdentityIQ problems fall into six families: onboarding and aggregation, access requests and provisioning, lifecycle events (joiner, mover, leaver), certifications, scheduled tasks, and custom rules or workflows. Each family leaves evidence in predictable places, and once you know them, troubleshooting stops being guesswork.

This guide is for freshers, support engineers moving into IAM, and working admins. It applies to IdentityIQ 8.x. Menu locations shift between versions and patch levels, so it describes screens in general terms rather than exact click paths.

What is the step-by-step approach to troubleshooting in SailPoint IIQ?

The step-by-step approach to SailPoint IIQ troubleshooting has six stages: scope the issue, read the task result or request status, check Syslog and incident codes, raise Log4j 2 to debug for the right class, inspect object XML and configuration, then fix, retest on one identity and revert debug logging.

1. Reproduce and scope the issue — one identity, one application, or everything?
2. Read the task result or request status first — it usually names the failing object.
3. Check Syslog and incident codes — find the stack trace behind a UI error.
4. Raise Log4j 2 to debug for the right class — reproduce once, then read the log.
5. Inspect the object XML and configuration — compare stored values with what you expected.
6. Fix, retest on one identity, revert debug logging and document.

Step 1. Reproduce and scope the issue

Ask what is affected, when it started and what changed around then (a deployment, a patch, a rotated service-account password). A problem limited to one identity usually points to data; a problem across every identity usually points to configuration or connectivity.

Step 2. Read the task result or request status first

Every task writes a Task Result with a status, messages and statistics such as accounts scanned. Access requests show their status and history on the request details page. The message there often names the failing identity, account or rule.

Step 3. Check Syslog and incident codes

An incident code shown in the UI points to a Syslog entry in the IIQ database. Search for it in the Syslog view under Advanced Analytics to see the stack trace and the class that failed.

Step 4. Raise Log4j 2 to debug for the right class

Enable debug only for the class involved in log4j2.properties, reload the logging configuration, reproduce the issue once, and read the log for that time window.

Step 5. Inspect the object XML and configuration

Open the Identity, Link (account), Application, TaskResult, WorkflowCase or IdentityRequest on the Debug pages. Empty attributes, wrong case or a missing schema attribute usually show up here.

Step 6. Fix, retest on one identity, revert debug logging and document

Make the smallest change that addresses the proven cause and test it on one identity before rerunning a full task. Then switch debug logging off, because verbose logging slows IIQ and fills disks, and record the symptom, cause and fix.

Where are SailPoint IIQ logs, and how do you enable Log4j debug logging?

SailPoint IIQ logging is controlled by the log4j2.properties file in the IdentityIQ web application's WEB-INF/classes folder. Depending on the configured appenders, output goes to a dedicated file such as identityiq.log or to the application server's console log, such as catalina.out on Tomcat. Debug logging is enabled per class.

identityiq.log vs catalina.out

If the root logger only references the console appender, IIQ messages land in the application server's standard output, which on Tomcat for Linux is usually catalina.out. If a rolling file appender is configured and referenced, IIQ writes to its own file, commonly identityiq.log. Open log4j2.properties and check which appenders your loggers reference. A missing log file is often a folder-permission problem, not a logging problem.

log4j2.properties: the two-line logger syntax

IdentityIQ 8.x uses Log4j 2, configured in log4j2.properties; older versions used Log4j 1.x and log4j.properties, so first check which file your installation has. In Log4j 2 properties format, each logger needs a name line and a level line sharing a key:

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

The old one-line Log4j 1 style (log4j.logger.sailpoint.api.Aggregator=debug) is not understood by Log4j 2, so a snippet copied from an old forum post appears to do nothing on 8.x. The shipped file contains many commented-out loggers for common classes; uncommenting the right pair is often quickest. Never switch the root logger to debug.

Reloading logging without a restart

You do not need to restart the application server. The Debug pages include an option to reload the logging configuration. The IIQ console, the command-line tool that ships with IdentityIQ, can also reload logging, print an object's XML and run a rule, which helps when the UI is unavailable; use the console's built-in help to list the exact commands for your version.

Syslog vs the log file

Syslog is a table in the IIQ database that stores higher-severity events with an incident code and stack trace. The log file holds everything your Log4j 2 levels allow, including debug detail. Syslog tells you what failed and when; the log file tells you why.

Debug pages and object XML

The Debug pages let an administrator browse objects by type and read their XML, which shows the real stored state of an Identity, Link or WorkflowCase. Read freely, but do not edit production objects casually: a Debug-page edit skips the validation the normal UI performs.

How do you troubleshoot application onboarding and aggregation issues?

To troubleshoot aggregation in SailPoint IIQ, start with the aggregation Task Result for errors and account counts, then check the service account's permissions, search scope and filters, the schema's identity attribute, and correlation settings. Raise the aggregator and connector loggers to debug only if the task result does not explain the failure.

Test connection passes but aggregation returns zero accounts

A successful test connection usually proves only that IIQ can authenticate. Zero accounts typically means the service account cannot read the objects, the search scope is wrong, or a filter removes everything. Compare filters with the target's data and confirm read rights with its administrator. See our application onboarding guide.

Accounts aggregate but stay uncorrelated

Common causes are a blank or differently formatted correlation key (case, whitespace, leading zeros), the wrong attribute pair, or aggregating a target before the HR source has created identities. After fixing the logic, rerun aggregation with optimisation disabled. The full repair path is in our guide to fixing uncorrelated accounts in SailPoint IIQ.

Aggregation timeouts and large applications

Check connector timeout and page-size settings, prefer delta aggregation where supported, and consider partitioning to split work across request threads. The connector's debug log shows whether IIQ was waiting on the target. Task options are explained in aggregation and refresh tasks.

Schema and identity attribute errors

Each account schema needs an identity attribute (the unique account ID) that the connector actually returns. If it is empty or misnamed, aggregation reports a null identity or skips accounts. Compare the schema with a raw account from the connector.

How do you troubleshoot access request issues?

To troubleshoot a SailPoint IIQ access request, follow it from its IdentityRequest record to the WorkflowCase that processes it, check for pending work items or exceptions in workflow steps, then read Provisioning Transactions and the connector error. Most stuck requests are waiting on an approval, a failed rule or a provisioning error.

Request approved but never provisioned

Note the request's current step. If it is waiting, look in the WorkflowCase for an open or orphaned work item, such as one assigned to an inactive approver. If it stopped after approval, a custom rule or script step has usually thrown an exception; Syslog shows the stack trace. Setting the workflow's trace variable to true on a test request shows each step executed. See our guide to custom workflows.

Provisioning failed: Provisioning Transactions and retries

Provisioning Transactions, in the Admin Console in IIQ 8.x, record each provisioning attempt with its status and the connector's error. IIQ retries only when the connector reports a retryable result; for many connectors, the application's retryableErrors list decides which error strings qualify.

Whether IIQ retries, how many times and how long it waits between attempts all come from configuration, so check the retry settings in your own environment instead of assuming a default. Once retries are exhausted, fix the cause and raise a fresh request. More in our explainer on provisioning in SailPoint IIQ.

Request status not updating after the target changed

The connector may have returned a queued status, or verification may depend on the next aggregation. Run a targeted aggregation of that account and recheck the IdentityRequest items before raising a duplicate request.

How do you troubleshoot LCM joiner, mover and leaver issues?

Most SailPoint IIQ joiner, mover and leaver problems trace back to identity refresh. Lifecycle events are evaluated during identity refresh with the Process events option enabled, after the HR source has been aggregated. If the refresh skips that option, runs before aggregation, or the trigger never matches, the event will not fire.

Joiner event not triggering

Check in order: the event is enabled; the refresh has Process events on; HR aggregation ran before the refresh; and the identity meets the trigger and any population filter. A start-date trigger already in the past, or a condition on an unpopulated attribute, never matches. Background is in our guide to lifecycle events (Joiner to Rehire).

Joiner firing multiple times

The trigger probably stays true on every refresh, such as a rule that checks a value rather than a change, or two refreshes overlap on the same identities. Prefer change-based triggers and avoid overlapping schedules.

Mover not detected

A mover needs an attribute change, so department or manager must be mapped from HR and stored on the identity. Compare the identity XML before and after aggregation to confirm the value really changed.

Leaver not disabling accounts

The target connector may not support disable, the application may lack a provisioning policy, or it may be read-only, so IIQ creates a manual work item instead. Check the plan in the workflow trace and each result in Provisioning Transactions.

How do you troubleshoot certification issues?

To troubleshoot SailPoint IIQ certifications, check the generation Task Result first, then confirm the campaign's scope actually contains items. Certifications that complete instantly usually have nothing in scope, missing entitlements usually mean identity data is stale and needs a refresh, and failed revocations are traced through Provisioning Transactions.

Certification completes instantly or shows no items

If filters, exclusions or the selected applications leave nothing in scope, the review may sign off immediately. Check the campaign filters and confirm the target identities hold accounts on those applications.

Entitlements missing from a manager certification

Certifications use the entitlement data stored against each identity. Run an identity refresh with the entitlement-refresh option for affected identities, check the manager attribute, then regenerate. See our access certification guide.

Generation looks stuck

Large campaigns can take a long time. Watch the Task Result and check the log for certification errors before terminating; restarting a large generation only restarts the wait.

Revocations not provisioned

Check whether remediation was automatic or created a work item, then read Provisioning Transactions for the connector error. The same retry rules apply.

How do you troubleshoot task failures and stuck tasks?

To troubleshoot SailPoint IIQ task failures, read the Task Result's status, messages and statistics first, then check Syslog and the logs for the task's time window. Tasks stuck after a server restart usually need terminating and their stale results cleared, while slow tasks point to partitioning, thread or database problems.

Reading Task Results

A Task Result shows pending, success, warning or error status with messages and counters. A warning with high counts matters too: thousands of skipped accounts may signal a filter problem rather than a crash.

Task stuck after a server restart

The result can stay running with nothing behind it. Terminate it from the task screens or the Admin Console, confirm nothing is still active on any server, then clear the stale result and rerun. Never delete a result while its task is genuinely running.

Refresh or aggregation running slowly

For partitioned tasks, check whether partitions are waiting for request threads, whether every server meant to run them is up, and whether the logs show duplicate-key or lock-timeout errors. One bad identity can repeatedly fail a partition.

Debugging rules and workflows

In BeanShell rules, use a named logger, add a matching pair in log4j2.properties, log key inputs and the return value, and guard against nulls. For workflows, set trace to true on a test run. See rules and BeanShell and BeanShell interview questions.

Quick reference: SailPoint IIQ troubleshooting cheat sheet

This cheat sheet maps the most common SailPoint IIQ symptoms to their likely cause, the first place to check and the usual fix. Use it as a starting point, then confirm the cause with the 6-step method before changing configuration, especially in production environments.

What SailPoint troubleshooting questions are asked in interviews?

SailPoint IIQ interviews test troubleshooting through scenarios: uncorrelated accounts, an approved request that never provisioned, a joiner that did not fire, a certification with no items, or a task stuck after a restart. Interviewers want a structured method, the exact objects you would check, and a safe fix.

Structure every answer the same way: symptom, first place to look, how you confirm the cause, the fix, and prevention. Practise with our scenario-based interview questions, the SailPoint IIQ interview questions guide and the interview question bank.

How is troubleshooting taught in a live SailPoint IIQ course?

At IAM Careers, troubleshooting is Module 15 of the 15-module SailPoint IIQ course. It is taught through trainer-led live walkthroughs on Zoom: Oishi demonstrates real troubleshooting scenarios step by step and students follow along with guided hands-on practice, after first learning the modules that produce those failures.

Module 15 covers a step-by-step troubleshooting approach; checking logs and configuration (Log4j debug logging, IIQ and application-server logs, Syslog, task results, debug pages and object XML); and onboarding, access request, LCM, certification and task failure issues. It comes last because you can only diagnose what you understand. See the full 15-module curriculum.

The live SailPoint IIQ course runs 45 days, costs ₹25,000 and is capped at 15 students per batch, with recordings and LMS access for 2 years. Oishi has 15 years of enterprise IAM experience. We provide placement assistance and award an IAM Careers certificate of completion. Coming from support? Read support engineer to SailPoint IAM.