Circular hierarchies: what they are and how to fix them

What is a circular hierarchy? 

Eletive builds its reporting structure from the manager information in your source system (for example, each user's "manager" or "reports to" field). For this structure to work, every reporting line must eventually lead upward to someone with no manager, without looping back on itself.

A circular hierarchy happens when that chain loops back to where it started, instead of leading to a top. This can happen in two ways:

• Self-reference: a person is set as their own manager (User A → User A).
• A loop between two or more people: for example, User A reports to User B, and User B reports back to User A (or a longer chain: A → B → C → A).

Because there's no clear "top" of the chain in either case, Eletive can't determine the reporting structure for the people involved, and the affected user(s) are skipped during sync until the loop is corrected in the source data.

Note that the same kind of loop can also occur in an organizational unit/segment hierarchy (for example, a department set as its own sub-department), not only in people's manager fields. The cause and the fix are the same principle: find where the chain loops back on itself and break it.

Why does this happen? 

A circular hierarchy is almost always the result of manager data in the source system (your HRIS, identity provider, or upload file) that hasn't been fully updated. Common triggers include:

• A person is (incorrectly) listed as their own manager.
• Two managers have been set to report to each other, often after a reorganization.
• A manager change wasn't saved correctly for everyone affected, leaving a partial loop.
• A terminated or removed employee is still referenced as someone's manager. Note that if your integration matches users by a unique ID (rather than email), that person may still need to remain part of the sync data so other users who report to them can still be matched correctly — removing them entirely can itself cause errors.

How to identify the affected users 

How much detail you get depends on how your manager data is synced into Eletive:

1. Mass Edit user file. If your file upload contains a circular hierarchy, Eletive generates an error log you can review. This log lists the rows/users involved, so you can go directly to the source of the problem, correct the manager column for those users, and re-upload the file.
2. HRIS integration (via Apideck). You'll receive a notification that a circular hierarchy was detected, but the notification itself does not tell you which users are involved. To find them:
   • Go to Settings → Integrations, and run a Test Integration (test run) before your next scheduled sync.
   • This test output a mass edit user file that you can import as Mass edit file (like option 1 above. That mass edit upload produces an error log you can review, showing which users are causing the loop.
   • Correct those users' manager data in your source HRIS, then run the test again and upload the latest test run to confirm the loop is resolved before the next live sync.
3. SCIM. As with HRIS, you'll get a notification that an error occurred, but SCIM does not provide details about where the loop is, and there is currently no built-in way to pinpoint the affected users from within Eletive.
   • If you already know which user's update is failing — for example, from your identity provider's own sync logs, or because you recently changed a specific person's manager — start by reviewing that person's reporting chain for a loop.
   • Otherwise, review any recent manager changes in your identity provider as a starting point, since these are the most common cause of new circular hierarchies.

How to fix it 

Once you've identified the user(s) involved:

1. Check whether any of them are set as their own manager.
2. Check whether two or more managers point back to each other in a loop.
3. Correct the manager field(s) in your source system (HRIS, identity provider, or upload file) so the chain leads to a single top-level manager with no loop.
4. Re-sync (or re-upload, for Mass Edit) and confirm the circular hierarchy notification no longer appears.

If you've reviewed your manager data and can't find where the loop is — particularly for SCIM, where Eletive currently can't show you the affected users directly — contact Eletive support. To help us investigate faster, you can grant our support team temporary access to your organization via Settings → General.