How the sync works

CloudMod keeps roles and nicknames in step across the servers of a network. This page explains when that happens, what exactly gets changed, and what to do when something looks out of date. For what a main server and a sub-server are, see Main server vs. sub-server.

The short version

What happens	What CloudMod does	How fast
A member gets or loses a role that is part of a role rule	Adds or removes the target roles on the other servers	Within seconds
A member joins a sub-server	Gives them the roles your rules derive for that server, then applies their main-server nickname	Within seconds
A member changes their nickname on the main server	Copies it to every sub-server	Within seconds
A member changes their nickname on a sub-server	Copies it to the main server and from there to the other sub-servers	Within seconds
A member leaves a server	Removes target roles elsewhere that no source role supports any more	Within seconds
Nothing happens for a while	The periodic check compares every member and reports or corrects drift	Every hour (every 30 minutes on Network and Grid)
An admin runs /sync user @member	Roles and nickname of that one member, right now	On demand

Role sync

Roles move along your Role Rules (Sub-Servers and Role Rules pages). Whoever holds a source role gets the target roles on the other servers, and loses them again once no source role supports them. Three things are worth knowing:

• Only target roles are touched. A role that is not the target of any rule is never added or removed by CloudMod — not on the main server, not on a sub-server. Roles you assign by hand stay where they are.
• Removal is cautious. A target role is only removed when none of its sources are left. If two rules point at the same target and only one source goes away, the member keeps the role.
• Live first, check later. Role changes, joins and leaves are handled the moment they happen. The periodic check is the safety net for anything the live path missed — for example while the bot was offline.

If a role can't be assigned because it sits above CloudMod's own role, the log channel says so (Role can't be assigned), at most once per role per day. Fix the role order in Server Settings → Roles; /checkperms @member shows whether CloudMod can change a member's roles.

Nickname sync

Switch it on under Project settings → Server setup → Network → Sync nicknames. The main server is the source of truth, but changes travel both ways:

• A nickname set on the main server goes to every sub-server.
• A nickname set on a sub-server goes to the main server, and from there to all other sub-servers.
• When a member joins a sub-server, they get their main-server nickname right away, together with their roles. A member who has no nickname on the main server keeps whatever Discord shows by default.
• Each sub-server can opt out on the Sub-Servers page. An opted-out server neither receives nor sends nicknames.

The whole picture in one place: Nickname sync.

Discord sets hard limits here: no bot can rename a server owner, CloudMod's role must sit above the member's highest role, and it needs Manage Nicknames on that server. Details and fixes: Nickname sync isn't working for some users.

The periodic check

Every hour — every 30 minutes on the Network and Grid plans — CloudMod walks through the members of each network and compares what they have with what your rules say they should have. Nicknames are included for members who hold at least one synced role on the main server.

What happens with the result depends on Auto-Fix (Project settings → Behavior, see Dry-Run vs Auto-Fix):

• Auto-Fix on — mismatches are corrected on the spot: missing roles are added, stale nicknames are updated.
• Auto-Fix off — nothing is changed. The log channel gets a report of what is out of step, and you decide what to fix.

A check that finds nothing out of step stays silent — no "all in sync" message. When it finds drift, the log channel gets a short report: what was detected and, with Auto-Fix on, what was corrected. The report is the Drift reports log category — switch it off or route it to its own channel under Logging. /scan (admin) runs the comparison for your network right now and shows the result — it reports, it doesn't change anything.

Sync one member by hand

Admins can trigger a sync for a single member at any time, on the main server:

• /sync user @member — roles and nickname
• /sync role @member — roles only
• /sync nick @member — nickname only

The reply tells you what was applied, what was already correct, and what Discord refused (for example a server owner's nickname).

What the sync never does

• It never touches roles outside your rules, and it never renames bots or server owners.
• It recognises its own changes, so one sync never sets off another.
• In Dry-run mode it changes nothing at all — the log channel shows what it would do. Other plugins keep working.
• On a sub-server that is paused because your plan allows fewer servers than you have, roles and nicknames are not synced until you unpause it or change the plan. Ban enforcement stays active there.

When something looks out of date

1. Check the member on the main server: do they still hold the source role, and is their nickname what you expect? The main server is the source.
2. Run /sync user @member. The reply names the reason if Discord refused — usually role order or a missing permission.
3. Run /checkperms on the server in question to see whether CloudMod has the permissions it needs there.
4. If the member was on the sub-server before you switched nickname sync on, the next periodic check (with Auto-Fix) or /sync nick @member catches them up.