ReactionBot Documentation
Roles Troubleshooting
Diagnose and resolve the most common issues with ReactionBot's Roles module.
If ReactionBot isn't assigning or removing roles correctly, the problem is almost always related to permissions, role hierarchy, message configuration, or an incorrect dashboard setting. This guide walks through the most common solutions.
Role Isn't Being Assigned
Verify that the reaction role mapping is enabled.
Confirm the emoji matches exactly, including custom server emojis.
Ensure the Message ID points to the correct Discord message.
Check that ReactionBot has the Manage Roles permission.
Role Isn't Being Removed
Verify that 'Remove Role on Unreact' is enabled.
Ensure ReactionBot still has permission to manage the role.
Managed Discord integration roles cannot be removed by ReactionBot.
Reaction Does Nothing
Confirm ReactionBot can view the channel and read message history.
Verify the message still exists and has not been deleted.
Double-check that the configured emoji matches the reaction being used.
Role Hierarchy Problems
ReactionBot's highest role must always be above every role it assigns or removes.
If the target role is higher than ReactionBot, Discord will reject the role change.
Required Role Isn't Working
Verify that members already possess the configured Required Role.
If they do not, ReactionBot will intentionally ignore the reaction.
Verification Flow Stops
Ensure every verification step is enabled and correctly configured.
Verify that the reward role still exists and ReactionBot can manage it.
Check each message and emoji used within the verification flow.
Single Mode Isn't Removing Previous Roles
Verify every mapping belongs to the same Group ID.
Confirm the group is configured for Single Mode rather than Multi Mode.
Multi Mode Isn't Assigning Multiple Roles
Verify the role group is configured for Multi Mode.
Check that multiple mappings share the correct Group ID.
Dashboard Changes Don't Apply
Save the configuration after making changes.
Allow a few seconds for the dashboard and bot to synchronize.
Refresh the dashboard if necessary before testing again.
Run /diagnose
If you're still experiencing problems, run /diagnose in the affected channel.
The diagnostic report checks common permission and configuration issues and often identifies the problem immediately.
Still Need Help?
Join the ReactionBot Support Server if the issue continues.
When requesting support, include screenshots of your Roles configuration, role hierarchy, and the results of /diagnose.