Permissions and role hierarchy: why a Discord bot fails
Almost every "the bot doesn't work" report from administrators comes down to two causes, and neither is a fault in the bot: a missing permission, or a role misplaced in the hierarchy.
This guide explains both, in the order you should check them.
Two mechanisms, not to be confused
A permission determines what a bot is allowed to do on the server: ban, manage messages, manage roles. It is set on the bot's role, and can be overridden channel by channel.
The hierarchy determines who it can do it to. Discord forbids a bot from acting on a member whose highest role sits above its own, and from manipulating a role placed above its own — even with the Administrator permission.
So a bot can hold every permission and still fail. That is the most common case, and the most confusing, because nothing in the permission settings hints at it.
Diagnosis, in order
- Does the action fail for everyone, or only for some members? For everyone, it is a permission; for some only, it is the hierarchy.
- Open Server Settings, Roles, and check the bot's role carries the permission matching the action.
- Check the position of the bot's role in the list: it must sit above the roles of the members targeted and above the roles it grants.
- Check the permissions of the channel involved: a channel can locally deny what the role globally allows.
- Check the action is not forbidden by Discord itself — a server owner cannot be kicked or banned by anyone.
Which permissions to grant, by function
- Moderation: Kick Members, Ban Members, Manage Messages.
- Levels with automatic roles: Manage Roles, and the bot's role above the granted roles.
- Welcome and verification: Manage Roles, View Channels, Send Messages in the welcome and validation channels.
- Polls: Add Reactions, on top of sending messages.
- Auto-moderation: Manage Messages, and read access to the monitored channels.
What the Administrator permission does not do
Giving a bot Administrator grants every permission at once, but changes nothing about the hierarchy. An administrator bot sitting at the bottom of the role list is still unable to act on half the server.
It is also a poor default: a permission a bot does not use is a permission it should not hold, and Administrator includes deleting channels and altering the server. Better to grant the permissions matching the modules actually enabled.