Discord’s permission system relies on a strict role hierarchy. When a bot cannot perform actions like assigning roles or kicking members, the root cause is often a misconfigured role position. Many server administrators assume that giving a bot the Administrator permission is enough to bypass all restrictions. This is not true. The bot’s highest role must sit above the target user’s highest role for specific moderation commands to work. This article explains exactly how the hierarchy affects bot operations and how to fix permission failures step by step.
Key Takeaways: Discord Role Hierarchy and Bot Permissions
- Server Settings > Roles > drag bot role above target roles: The bot’s highest role must be positioned above any role it needs to manage.
- Bot role must have the Manage Roles permission: Even if the bot is an administrator, the Manage Roles permission must be explicitly enabled on its role.
- User Settings > Advanced > Developer Mode: Enables right-click copying of user IDs for testing bot commands without hierarchy conflicts.
Why Discord Role Hierarchy Blocks Bot Actions
Discord uses a role hierarchy system where roles are ranked by their position in the Server Settings > Roles list. The role at the top of the list has the highest rank. When a bot tries to perform an action on a user, Discord checks the bot’s highest role position against the target user’s highest role position. If the bot’s role is lower or equal, the action is denied.
This applies to all moderation commands: kicking, banning, muting, and assigning roles. For example, if a bot has a role at position 5 and a member has a role at position 3, the bot cannot kick that member because its role is lower. The same rule applies when the bot tries to assign a role to itself or another user. The bot cannot assign a role that is positioned at or above its own highest role.
Another common misconception is that the Administrator permission bypasses the hierarchy check. Administrator grants access to all permissions, but the hierarchy check is separate. Even with Administrator, a bot cannot act on a user with a higher role. The bot’s role must still be positioned above the target user’s role.
Steps to Fix Bot Permission Failures Caused by Role Hierarchy
- Open Server Settings
Right-click your server icon in the left sidebar. Select Server Settings from the context menu. - Navigate to the Roles section
In the left menu under User Management, click Roles. You will see a list of all roles on your server, ordered from highest to lowest. - Locate the bot’s role
Find the role assigned to your bot. If you have multiple roles on the bot, find the highest one. The bot uses its highest role for hierarchy checks. - Drag the bot role above target roles
Click and drag the bot’s role upward in the list. Position it above any role that the bot needs to manage. For example, if the bot should kick members with the Moderator role, drag the bot role above Moderator. - Verify the Manage Roles permission
Click the bot role name. Under General Permissions, make sure the Manage Roles toggle is enabled. This permission allows the bot to assign and remove roles from other users. - Save changes and test
Click Save Changes at the bottom. Use a test command like !kick @User or !mute @User to confirm the bot now works on users with lower roles.
If Discord Bot Still Cannot Perform Actions After the Fix
Bot role is still below a role it needs to manage
Check the roles list again. The bot role must be above every role it will assign or manage. If you have multiple roles, ensure the bot role is at the top of the list. Drag it above all roles except the default @everyone role, which should remain at the bottom.
Bot lacks the necessary permission on the role
Even with the correct hierarchy, the bot must have the specific permission enabled. For kicking, the Kick Members permission must be on the bot role. For banning, Ban Members. For muting, Mute Members or Time Out Members. Open the bot role and check each permission individually.
Bot is trying to assign a role higher than itself
If the bot tries to assign a role that is positioned at or above its own highest role, the action fails. For example, if the bot role is at position 2 and the Admin role is at position 1, the bot cannot assign the Admin role. Move the bot role above any role it needs to assign.
Bot is using an outdated command or code
Some older bot commands may not check hierarchy correctly. Update the bot to the latest version or contact the bot developer. Check the bot’s support server for known issues with specific commands.
| Item | Incorrect Setup | Correct Setup |
|---|---|---|
| Bot role position | Below Moderator role | Above Moderator role |
| Manage Roles permission | Disabled | Enabled |
| Bot role and target user role | Equal position | Bot role strictly higher |
Now you understand exactly how Discord’s role hierarchy affects bot operations. The bot’s highest role must be positioned above any role it needs to manage or assign. Check the Manage Roles permission on the bot role and ensure it is enabled. As an advanced tip, use Developer Mode to copy user IDs and test commands on specific users without worrying about hierarchy conflicts. This approach saves time when debugging permission issues.