Reaction Roles: Panels, Emojis and Troubleshooting

With reaction roles, members choose their roles themselves: you post a panel message with emoji mappings. Anyone who reacts with an emoji gets the matching role, and anyone who removes the reaction loses it.

This page is the reference: how panels are created, which limits apply and how Kage processes reactions. For a short walkthrough, see the guide Setting up reaction roles.

Requirements

• Access to the module: You sign in to the dashboard with Discord and need the Manage Server permission (or access granted for this module).
• Roles in Discord: Create the roles that should be assigned by reaction.
• Role order: Kage's role must be above these roles in the role list. Kage also needs the Manage Roles permission (part of the standard invite).
• In the panel channel: Kage needs Send Messages, Embed Links and Add Reactions.

Creating a panel

In the dashboard under Reaction roles, you fill in "Create new panel" and click Create & post panel:

1. Choose the channel where the panel should appear.
2. Enter a title. Without a title, Kage uses "Rollen wählen" (German).
3. Optionally write a description.
4. Under "Emoji → role", add at least one mapping: an emoji and a role.
5. Kage checks your input: the channel and every role must exist, and each emoji may appear only once in the panel.
6. Kage posts a message with the title, your description and one line "emoji — @role" per mapping, and adds all the reactions itself.

Important limits:

• Standard emojis only. Discord does not accept custom server emojis for this feature. If Discord rejects an emoji, the panel message is already in the channel. Delete it by hand in Discord and create the panel again.
• At most 20 mappings per panel, because Discord allows at most 20 different reactions per message.
• At most 10 panels per server. Next to the panel list, the dashboard also shows how many panels your plan provides (Basic 3, Premium 25, Enterprise unlimited).

An existing panel cannot be edited. Delete it with Delete in the dashboard (this also removes the message in Discord) and create a new one.

How Kage processes a reaction

1. Kage watches reactions on all messages of the server. It only reacts to messages that are stored as a panel.
2. Reactions from Kage itself and from other bots are ignored.
3. If "Reaction roles active" is off, nothing happens.
4. If the emoji matches a mapping of the panel, Kage assigns the matching role. If someone removes the reaction, Kage removes the role again.
5. If the role no longer exists, Kage skips the mapping.
6. In the module's Logs tab, every assignment ("Rolle … an … vergeben", in German) and every removal appears.

Kage has no single-choice mode: each reaction assigns its role independently of the others. Anyone who clicks several emojis gets several roles. The panel keeps working after a bot restart.

Settings at a glance

There are no slash commands for reaction roles.

Checking the result

1. Panel: Check that the message is in the channel and that the bot added all reactions below it.
2. Practical test: React to an emoji with a second account. It should get the role immediately and lose it again when the reaction is removed.
3. Log: The Logs tab in the module shows assignment and removal.

Troubleshooting

Nothing happens when reacting

Check that "Reaction roles active" is on and saved. Check that the panel is still in the "Existing panels" list and that the message was not deleted in Discord. Deleted messages stay in the list until you delete the panel in the dashboard.

The role is not assigned

Usually it is the role order: Kage's role must be above the role. The Manage Roles permission must also be present. Discord shows no message for this, the error appears only in the operating log.

The panel cannot be created

Check the message in the dashboard. Common causes: no channel chosen, no mapping, an emoji used twice, a role that no longer exists, more than 20 mappings, 10 panels already, or Kage may not post in the channel.

An emoji is rejected

It is a custom server emoji or an emoji Discord does not know. Use a standard emoji. You delete the already posted panel in Discord and create it again.

Members get several roles although only one is wanted

There is no single-choice mode. Split the roles across separate panels and tell members to choose only one emoji, or use role panels with buttons or select menus.

Further reading

More about role problems is in the guide Role troubleshooting. If newcomers should receive their role automatically: Auto roles.