Understanding Manager Hierarchies and Loop Detection in Acorn

Acorn tracks who manages who using a simple one-directional hierarchy. This article explains how manager relationships work, what causes a "loop" in that hierarchy, and how Acorn automatically catches loops before they can cause a problem — whether they come from an HR feed upload, a bulk user upload, or a manual update in the platform.

How the manager hierarchy works

Acorn keeps track of who manages who using one simple rule: each person has one manager.

One manager each — every user has zero or one direct manager, never more than one.
Leave it blank at the top — if a user has no manager, leave the manager_username field empty. This marks them as the top of the tree (for example, a CEO or department head).
Any number of direct reports — a manager can have as many people reporting to them as needed, with no limit.

A manager is set using the manager_username field in your HR or bulk feed, or the Supervisor Username field when updating a user directly in the platform.

What is a "loop", and why does it matter?

A loop happens when the chain of managers eventually leads back to someone who's already in it — in other words, someone ends up managing their own manager, a few steps up the chain.

For example: A manages B, B manages C, and C manages A. The circle closes, and none of the three has a clear "top of the tree".

Acorn's hierarchy only works when it flows one way, from the top down. If a loop exists, there's no valid top, and anything that relies on the hierarchy — such as reports, cohorts, or supervisor permissions — can't work properly for the people involved.

Loops are caught before anything is saved

Acorn checks your entire set of manager relationships — the new ones in an upload, plus everything already saved — before saving anything at all. If a loop is found anywhere in that combined picture:

Nothing is saved. The upload is rejected as a whole, so your existing hierarchy stays untouched.
You get a clear error message naming the exact users involved, for example: user_a → user_b → user_c → user_a.
You can fix the data and resubmit. Nothing else needs to be redone.

This also applies when updating a single user's manager manually through Browse and Update Users. If setting the Supervisor Username field would create a loop, or the manager entered doesn't exist or isn't in the same tenancy, the update is blocked with a clear error message on the field and nothing is saved. Acorn will never silently work around a loop — you'll always get an explicit, readable error.

A loop doesn't have to appear in a single file, either — it can form gradually across two separate uploads. For example, if one upload sets User A to report to User B, and a later upload sets User B to report to User A, the second upload would be rejected because Acorn checks the new data against everything already saved. This is most likely to happen during temporary handover periods, such as someone covering for their manager while on leave — if you set up a temporary reporting change like this, double-check who reports to whom once the handover ends.

A quick checklist before you upload a feed file

No circular chains — following manager_username for any user should never loop back to someone already in that chain.
No self-management — a user's manager_username should never be their own username.
Managers must exist — a referenced manager should already exist (or be included in the same file) and be in the same tenancy.
Blank means "top of the tree" — leave manager_username empty for anyone with no manager.
You don't need to resend everyone — partial feeds are fine. Just send the rows that changed and the rest stays as-is.

Here's what a valid, one-directional structure looks like: a CEO with no manager, a VP who reports to the CEO, a manager who reports to the VP, and staff who report to the manager — each link pointing only upward, with no one appearing twice in the chain. A loop would look like: a VP who reports to a manager, a manager who reports to a staff member, and that staff member reporting back to the VP — this would be rejected because the chain closes on itself.

Updating a supervisor directly in the platform

You can also update a manager relationship without an HR feed:

Go to Browse and Update Users.
Open the user you want to update.
Enter the new manager in the Supervisor Username field.

The same loop protection applies here as it does to feed uploads.

Using both an HR feed and manual updates

Both the HR feed and the platform update the same underlying data, so a change made one way is always visible to the other — there's no separate, out-of-sync copy to worry about. But that also means the two can affect each other:

Feed sends a different manager — the feed's value wins, and your manual update is replaced.
Feed sends a blank manager — this is treated as "no supervisor", and your manual update is removed silently.
Feed leaves the column out entirely — this is safe. The feed won't touch anyone's supervisor at all.

To avoid losing a manual update:

Pick one source of truth — manage supervisors through either the HR feed or the platform, not a mix of both, wherever possible.
If the feed is your main source, keep manager_username accurate and complete, since a blank value removes an existing supervisor, even one that was set manually.
If you manage some supervisors manually while your feed still includes manager_username, make sure those same people are represented correctly in the feed too, or your next upload will overwrite the manual change.
If you want the feed to never touch supervisors, leave the manager_username column out of your feed file entirely and manage all supervisors through the platform instead.
If a supervisor seems to have disappeared, check your most recent feed upload log — a mistyped manager_username won't show as an error, just a quiet removal.

Need a hand?

If you get a loop error and aren't sure how to resolve it, or you'd like Acorn Support to double-check your feed file before you upload, contact us at support@acorn.works and we'll help you sort out the manager relationships before you resubmit.