Permissions
What the bot needs, why it needs it, and how to diagnose a permission failure.
Most reports of "the bot is broken" are a permission the bot does not have, or a role hierarchy that stops it using one it does. Both are visible before you file anything.
The two rules
- A permission the bot does not hold in a channel cannot be used in that channel, regardless of what it holds server-wide. Channel overwrites beat server permissions.
- A bot cannot act on a member whose highest role is above the bot's highest role, and cannot manage a role above its own. This holds even with Administrator.
What each module needs
| Module | Permissions | Why |
|---|---|---|
| Logging | View Channel, Send Messages, Embed Links, Manage Webhooks | Logs are posted through a webhook so they survive the bot being offline. |
| Moderation | Kick Members, Ban Members, Moderate Members, Manage Roles | Manage Roles is what applies and removes the mute or jail role. |
| Protection | View Audit Log, Manage Roles, Ban Members | The audit log is how the bot attributes a destructive action to a person. |
| Tickets | Manage Channels, Manage Roles, Send Messages, Embed Links | Tickets create and rename channels and grant access per user. |
| Levelling | Send Messages, Embed Links, Attach Files, Manage Roles | Attach Files is for rank cards; Manage Roles is for level rewards. |
| Giveaways | Send Messages, Embed Links, Add Reactions | Entry and drawing both happen in the channel the giveaway was posted to. |
Diagnosing a failure
- The bot replied with an error: it names the missing permission and the channel. Fix that one.
- The bot did nothing at all: check the target's highest role against the bot's. This is the hierarchy rule and it produces silence, not an error.
- It works in one channel but not another: a channel overwrite is removing the permission there.
- It worked yesterday and not today: a role was moved. Discord does not announce this.