Syncing Discord roles and server groups
Automatically granting a donor role in Discord by LuckPerms group and the reverse link: setup, verification, and common mistakes.
Updated August 13, 2026
Role linking is the main practical benefit of DiscordSRV: buy a rank and get a Discord role automatically.
Setup
plugins/DiscordSRV/synchronization.yml:
GroupRoleSynchronizationGroupsAndRolesToSync:
'vip': '123456789012345678'
'premium': '234567890123456789'
GroupRoleSynchronizationOneWay: false
GroupRoleSynchronizationCycleTime: 5
On the left is the LuckPerms group, on the right is the Discord role ID (right-click the role with developer mode enabled).
Account linking
/discord link
The player receives a code and sends it to the bot in a direct message. Synchronization is impossible without linking.
Two-way mode
OneWay: false means that a Discord role also grants a group on the server. Convenient, but dangerous: whoever hands out roles in Discord effectively hands out ranks on the server. For donor groups, one-way mode (server → Discord) is safer.
Bot permissions
The bot's role must be higher than the roles it manages in the Discord role list, otherwise it won't be able to assign them. This is the cause of 90% of "synchronization doesn't work" cases.
Checking
/discordsrv link Nick
/discordsrv debug
The log shows which roles the bot is trying to assign and why it failed.
