Discord: role not given, missing permission, bot role too low

In short. A member gets a role on the site, but their linked Discord role does not arrive? Discord refused. The member's page (Administration → Members) shows the latest Discord calls: a 403 refusal means "missing permission".

Causes, in order #

1. The bot's role is too low #

A bot can only give roles placed below its own.

1. Discord: Server Settings → Roles.
2. Drag the bot's role above every role it must give.
3. In Agora, on the member's page: Resync their Discord roles.

Agora checks this before you save: in Administration → Configuration → Discord connection, a role placed above the bot (or at the same rank) is greyed out in the list, with the reason, and picking it anyway is refused when saving. If you move roles later, the mappings that became impossible show in red under Mappings Discord will refuse. That list covers the groups' roles and the MDT rank roles. Under each problem, the Open in the Discord app button takes you to the screen where you fix it (Server Settings → Roles, Integrations), and Open the developer portal (Bot tab) takes you to your application (the Client ID must be filled in). These buttons only open the desktop app: on mobile, on Linux or in the browser they may do nothing, so follow the path written beside them.

To understand why the order matters, see the official help: Discord Roles and Permissions.

Tip, desktop app only. If you know your server's ID (see Create and set up your Discord bot, step 6), paste into your browser's address bar discord://-/guilds/ID/settings/roles (Roles), discord://-/guilds/ID/settings/integrations (Integrations: you see whether the bot is there) or discord://-/guilds/ID/settings/audit-log (Audit Log: who changed which roles), replacing ID with the server ID. These are unofficial shortcuts that may stop working; the path through Server Settings always works.

2. The "Manage Roles" permission is missing #

1. Discord: Server Settings → Roles → the bot's role.
2. Turn on Manage Roles.
3. Resync.

3. "Server Members Intent" is not enabled #

Discord developer portal → your application → Bot → turn on Server Members Intent. Shortcut: https://discord.com/developers/applications/ID/bot, where ID is your application's Client ID (the one in Administration → Configuration → Discord connection, block Discord login (OAuth)).

4. The role is managed by an integration #

Boost roles or another bot's roles (marked "managed by an integration") cannot be assigned. Pick another role in Administration → Configuration → Discord connection.

5. A role received on Discord does not add the member to their group #

This is the Sync Discord → Agora box of a group (see Discord roles, sync and "Suspended member"). Check in this order:

1. the box is ticked for that group (it is greyed out for a power group: administrator, moderator, rights, application examiners);
2. the member already has an account linked to their Discord (otherwise they are aligned at first sign-in);
3. the Recent problems panel of Administration → Configuration → Discord connection:

A member who leaves the server on their own is only removed from the group, in fallback mode, at the next re-read: click Resync. Each problem has its Open in the Discord app or Open the developer portal button, as above.

Messages in Administration → Configuration → Discord connection #

Bring everyone up to date #

After fixing it, Administration → Members → Resync every member → Start the resync. Keep the page open until it finishes.