You have assigned the Manage Roles permission to your Discord bot, but it still cannot assign or modify roles that appear above its own highest role. This is not a bug. Discord enforces a strict role hierarchy: a bot can only manage roles that are positioned below its own highest role in the server settings. This article explains the technical reason behind this limitation and provides clear steps to fix the role order so your bot works correctly.
Key Takeaways: Discord Role Hierarchy and Bot Permissions
- Server Settings > Roles > Drag to reorder: The bot’s highest role must be above any role it needs to manage.
- Discord API role hierarchy rule: A bot can only assign, edit, or remove roles that are strictly lower than its own top role.
- Bot role vs bot user role: The bot’s Manage Roles permission is granted by a role, but the hierarchy is based on the bot’s highest role position, not the permission source.
Why Discord Role Hierarchy Blocks Bot Role Management
Discord uses a vertical role hierarchy to prevent privilege escalation. Every role has a position number, with 1 being the lowest. The role at the top of the list in Server Settings > Roles has the highest position. A user or bot can only manage roles that have a lower position than its own highest role. This applies regardless of the Manage Roles permission.
When a bot has the Manage Roles permission, it can theoretically edit any role. However, the hierarchy check happens first. If the target role is at position 10 and the bot’s highest role is at position 8, the bot cannot manage the role at position 10 because that role is above its own. The permission is ignored in this case.
Another key detail: the bot’s role is not the same as the bot user. The bot user is a member of the server and has its own set of roles. The highest role among those roles determines the bot’s hierarchy position. If you assign a role to the bot that is lower than the role you want it to manage, the Manage Roles permission on that lower role does not override the hierarchy.
How Role Position Is Calculated
Role positions are integers. The topmost role in the list has the highest integer value, and the bottommost role has the lowest. When you drag a role upward in the server settings, its position number increases. Discord does not show the exact position number in the UI, but you can see the relative order visually.
Why the Manage Roles Permission Appears to Work for Some Roles
If your bot can manage some roles but not others, check the position of those roles relative to the bot’s highest role. Roles below the bot’s highest role are manageable. Roles above it are not. This is not a permission issue. It is a hierarchy issue.
Steps to Fix Bot Role Hierarchy for Manage Roles
Follow these steps to ensure your bot can manage the roles you intend. You need the Manage Roles permission on your own account to perform these steps.
- Open Server Settings
Right-click the server icon in your server list and select Server Settings. Alternatively, click the server name at the top left of the channel list and choose Server Settings from the dropdown menu. - Navigate to the Roles tab
In the left sidebar, click Roles. You will see a list of all roles in the server, ordered from highest to lowest position. - Identify the bot’s highest role
Find the bot user in the member list. Hover over the bot’s name to see its roles. Note the highest role assigned to the bot. If the bot has multiple roles, the one that appears highest in the Roles list is its highest role. - Identify the target role you want the bot to manage
This is the role you want the bot to assign, remove, or edit. For example, a “Member” role that the bot should assign to new users. - Drag the bot’s highest role above the target role
Click and hold the drag handle (six dots icon) next to the bot’s highest role. Drag it upward so it is positioned above the target role. Release the mouse button to save the new position. - Verify the bot can manage the target role
Test by using a bot command that assigns the target role to a test user. If the bot still fails, repeat step 5 and ensure the bot’s role is at least one position above the target role. - Check for role inheritance conflicts
If the bot has multiple roles, its effective hierarchy position is the highest among them. Remove any lower roles that might confuse the bot’s permission set. Keep only the roles necessary for the bot’s function.
If the Bot Still Cannot Manage Roles After Reordering
Bot Role Is Not the Highest Role in the Server
If you cannot drag the bot’s role above the target role because another role is already at the top, you may need to adjust the server owner’s role or an admin role. The server owner role is always the highest and cannot be moved. If the target role is the server owner role, no bot can manage it. Create a separate role for the bot to manage, such as a custom “Verified” role.
Bot Missing Manage Roles Permission on Its Own Role
The Manage Roles permission must be enabled on the role that is assigned to the bot. Open the bot’s role in the Roles list. Under General Permissions, ensure Manage Roles is toggled on. Also check that no other permission overrides are blocking it at the channel level.
Bot Code Does Not Handle Hierarchy Errors Gracefully
Some bot libraries throw an error when the hierarchy check fails. The bot may log a “Missing Permissions” or “Hierarchy” error. Check your bot’s console or logs for such errors. If the error is a hierarchy issue, reorder roles as described above.
Role Managed by Discord’s Built-in System
Discord’s system roles, such as the Nitro Booster role or the Server Owner role, cannot be managed by bots at all. These roles are locked by Discord. Your bot cannot assign or remove them regardless of role position or permissions.
Discord Role Hierarchy: Bot Role vs User Role vs System Role
| Item | Bot Role | User Role | System Role |
|---|---|---|---|
| Description | Role assigned to the bot user | Role assigned to a human member | Role created by Discord (Nitro Booster, Server Owner) |
| Can be managed by bot | Yes, if below bot’s highest role | Yes, if below bot’s highest role | No, never |
| Requires Manage Roles permission | Yes | Yes | No |
| Affected by role position | Yes | Yes | Yes, but cannot be moved |
Understanding the role hierarchy is essential for any Discord bot that manages roles. By placing the bot’s highest role above the target role, you enable the bot to assign, remove, and edit roles as intended. Always test with a non-critical role first. If you encounter persistent issues, check the bot’s error logs for hierarchy-related messages. For advanced setups, consider using Discord’s audit log to track role changes and verify that the bot’s actions are being applied correctly.