Role Reactor LogoRole Reactor

Troubleshooting Guide

Comprehensive troubleshooting guide for Role Reactor Bot covering common problems and their solutions.

Quick Problem Reference

🤖 Bot Not Responding

Bot does not respond to commands or emoji reactions

🚫 Roles Not Being Assigned

Reactions function but roles are not assigned

❌ Command Errors

Slash commands return error messages

🔄 Reactions Missing

Emoji reactions disappear or do not appear

📊 XP Not Tracking

Experience points are not being awarded

🎤 Voice Permissions Issues

Voice restrictions are not functioning

🎉 Welcome/Goodbye Not Working

Welcome or goodbye messages are not being sent

Common Issues

Common Causes:
  • Bot role positioned below managed roles in hierarchy
  • Missing "Manage Roles" or "Add Reactions" permissions
  • Role name spelling or case mismatches
  • Custom emojis not accessible to the bot

Bot Not Responding

Symptoms: Bot does not respond to commands or emoji reactions

Verify Bot Status

  • Confirm the bot is online (green status in member list)
  • Execute /ping to test bot responsiveness

Verify Permissions

  • Bot requires "Send Messages" permission
  • Bot requires "View Channel" permission
  • Verify channel-specific permissions

Check Role Position

  • Bot's role must be positioned above roles it manages
  • Navigate to Server Settings > Roles to verify hierarchy

Roles Not Being Assigned

Symptoms: Reactions function but members do not receive roles

Most Common Cause: Bot's role is positioned below the roles it is attempting to assign

Correct Role Hierarchy

  1. Navigate to Server Settings > Roles
  2. Drag the bot's role above all roles you want it to manage
  3. Test role assignment again

Verify Role Names

  • Ensure role names in the command match exactly
  • Check for typos or extra spaces
  • Role names are case-sensitive

Verify Bot Permissions

  • Bot requires "Manage Roles" permission
  • Verify in Server Settings > Roles > Bot Role > Permissions

Command Errors

Common Error Messages:

"Missing Permissions" or "Access Denied"

Solutions:

  • Verify you have "Manage Roles" or "Manage Server" permission
  • Confirm bot has necessary permissions
  • Verify you are using commands in the appropriate channel

Command Access:

  • Server owners (all commands)
  • Members with "Manage Roles" or "Manage Server" (admin commands)
  • Everyone (general commands such as /help, /ping, reactions)

"Role not found" or "Cannot assign role"

Solutions:

  • Verify role name spelling exactly (case-sensitive)
  • Confirm roles exist in the server
  • Verify bot role is positioned above target roles
  • The @ symbol is automatically stripped, so both 🎮:Gaming and 🎮:@Gaming are valid

Accepted Formats:

✅ Simple: /role-reactions setup title:Game Roles description:Pick your role! roles:🎮:Gamer,🎨:Artist
✅ With @: /role-reactions setup title:Choose Your Roles description:React to get roles! roles:🎮:@Gamer, 🎨:@Artist
✅ Role Mention: /role-reactions setup title:Select Roles description:Choose! roles:🎮:<@&123456789>

"Invalid format" or "Parse error"

Common Issues:

  • Missing commas between roles
  • Incorrect category format
  • Invalid emoji or role format

Correct Format:

✅ Basic: /role-reactions setup title:Game Roles description:Pick your role! roles:🎮:Gamer,🎨:Artist
✅ Multiple: /role-reactions setup title:Choose Your Roles description:React to get roles! roles:🎮:@Gamer, 🎨:@Artist, 📚:Reader

Reactions Missing

Symptoms: Emoji reactions do not appear or disappear

Verify Emoji Format

  • Custom server emojis (including animated) are supported
  • Unicode emojis (🎮📚🎵) are also supported
  • Ensure the bot has access to custom server emojis

Refresh Reactions Contact support to refresh reactions for a specific message. This resolves most reaction-related issues.

Verify Bot Permissions

  • Bot requires "Add Reactions" permission
  • Bot requires "Manage Messages" permission
  • Verify channel-specific permissions

XP System Not Working

Symptoms: Users are not earning experience points or levels are not updating

Verify XP System Status

  • Execute /xp settings to verify the system is enabled
  • Check if message XP, command XP, role XP, or voice XP are disabled
  • The XP system is disabled by default and must be enabled by administrators

Verify Cooldowns

  • Message XP: 60-second cooldown between messages
  • Command XP: 30-second cooldown between commands
  • Users will not earn XP if they are in cooldown

Verify User Activity

  • Users must be actively messaging or using commands
  • Voice activity requires users to be in voice channels
  • Role assignments grant 50 XP per role

Voice Permissions Not Working

Symptoms: Users with restrictive roles are not being disconnected or muted

Verify Bot Permissions

  • Bot requires "Move Members" permission to disconnect users
  • Bot requires "Mute Members" permission to mute users
  • Verify permissions in Server Settings > Roles > Bot Role

Verify Role Permissions

  • Role must have "Connect" permission disabled to disconnect users
  • Role must have "Speak" permission disabled to mute users
  • Check role permissions in Server Settings > Roles

Test Voice Restrictions

  • Assign a restrictive role to a test user
  • Have the user join a voice channel
  • Bot should automatically disconnect or mute them

Welcome/Goodbye System Not Working

Symptoms: Welcome or goodbye messages are not being sent

Verify System Status

  • Execute /welcome settings or /goodbye settings to verify it is enabled
  • System may be disabled in settings
  • Verify channel configuration

Verify Channel Permissions

  • Bot requires "Send Messages" permission in the configured channel
  • Bot requires "Embed Links" if using embed format
  • Verify channel-specific permissions

Test Configuration

  • Use test functionality if available
  • Verify message format and placeholders
  • Verify auto-role assignment if configured

Poll System Issues

Symptoms: Polls are not being created or are not functioning properly

Verify Permissions

  • You require "Send Messages" permission to create polls
  • Bot requires "Send Messages" in the channel
  • Verify you are using the command in the correct channel

Verify Poll Limits

  • Check if you have reached the server's poll limit
  • Execute /poll list to view existing polls
  • Delete old polls if needed

Verify Poll Status

  • Execute /poll list to view all polls
  • Verify poll has not already ended
  • Check poll duration settings
Best Practices:
  • Position your bot's role high in the role list to minimize issues
  • Review permissions after adding new bots or roles
  • Test changes in a private channel before deploying
  • Bookmark the FAQ and Common Issues pages

Permission Troubleshooting

Required Bot Permissions

Manage Roles

Required to assign and remove roles

Manage Messages

Required to manage role-reaction messages

Add Reactions

Required to add emoji reactions to messages

Send Messages

Required to reply to commands and errors

Read Message History

Required to access reaction events

View Channel

Required to read channel content

Embed Links

Required to create rich embedded messages

Manage Server

Required to manage server settings

Use External Emojis

Required to use emojis from other servers

Optional Permissions

Move Members

Required for voice channel disconnection (voice restrictions)

Mute Members

Required for voice channel muting (voice restrictions)

Permission Configuration

During Bot Invitation

  • Use the official invite link
  • Ensure all required permissions are selected
  • Do not modify permissions during invitation

Post-Installation

  1. Navigate to Server Settings > Roles
  2. Locate the bot's role
  3. Click "Permissions" tab
  4. Enable required permissions

Channel-Specific Permissions

  • Right-click channel > Edit Channel > Permissions
  • Add bot role if needed
  • Grant necessary permissions for that channel

Support Resources

Before Requesting Support

Please complete these steps first:
  1. Review this troubleshooting guide
  2. Check the FAQ
  3. Review Common Issues
  4. Test with a simple role message first

Support Channels

📖 Documentation

Comprehensive guides and examples

❓ FAQ Section

Quick answers to frequently asked questions

💬 Support Server

Join our Discord server for live assistance

🐛 Bug Reports

Report bugs through GitHub issues

Information to Provide

When requesting support, please provide:

  • Objective: What you are attempting to accomplish
  • Command Used: Exact command executed
  • Error Message: Exact error message received
  • Server Configuration: Role hierarchy and permissions
  • Steps Taken: Actions you have already attempted

Prevention Strategies

Setup Best Practices

Start Simple

  • Test with 2-3 basic roles first
  • Use simple role names without special characters
  • Use common emojis (🎮📚🎵)

Verify Before Expanding

  • Confirm basic setup functions correctly
  • Test role assignment with reactions
  • Verify bot permissions are correct

Plan Role Hierarchy

  • Position bot role near the top of role list
  • Group managed roles below bot role
  • Keep admin/mod roles above bot role

Maintenance

  • Regular Permission Audits: Verify bot permissions have not changed
  • Test After Changes: Test role assignment when adding new roles
  • Monitor for Issues: Check for broken reactions or assignment problems
  • Documentation Reference: Bookmark this troubleshooting guide

Still need assistance? Review the FAQ for more specific questions, or join our support server for community assistance.

Educational Server

Implementation example for an educational Discord server. Organize roles by subject and study style for efficient academic community management.

Common Issues

Frequently encountered problems with Role Reactor Bot and their solutions.