Troubleshooting Guide

Having issues with Role Reactor Bot? This guide covers the most common problems and their solutions.

Quick Problem Solver

🤖 Bot Not Responding

Bot doesn't react to commands or emoji clicks

🚫 Roles Not Being Given

Reactions work but roles aren't assigned

❌ Command Errors

Slash commands return error messages

🔄 Reactions Missing

Emoji reactions disappear or don't appear

Most Common Issues

Common Pitfalls:

Bot role below managed roles in hierarchy
Missing "Manage Roles" or "Add Reactions" permissions
Typos or case mismatches in role names
Using custom emojis the bot can't access

Bot Not Responding

Symptoms: Bot doesn't respond to commands or emoji reactions

Check Bot Status

Is the bot online? (Green status in member list)
Try /ping to test if bot responds

Verify Permissions

Bot needs "Send Messages" permission
Bot needs "Use Slash Commands" permission
Check channel-specific permissions

Check Role Position

Bot's role must be above roles it manages
Go to Server Settings > Roles to check hierarchy

Roles Not Being Assigned

Symptoms: Reactions work but members don't get roles

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

Fix Role Hierarchy

Go to Server Settings > Roles
Drag the bot's role above all roles you want it to manage
Test role assignment again

Check Role Names

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

Verify Bot Permissions

Bot needs "Manage Roles" permission
Check in Server Settings > Roles > Bot Role > Permissions

Command Errors

Common Error Messages:

"Missing Permissions" or "Access Denied"

Solutions:

Make sure you have "Manage Roles" permission
Check if bot has necessary permissions
Verify you're using commands in the right channel

Who Can Use Commands:

Server owners (all commands)
Members with "Manage Roles" (most commands)
Everyone (/help, /ping, reactions)

"Role not found" or "Cannot assign role"

Solutions:

Check role name spelling exactly
Make sure roles exist in the server
Verify bot role is above target roles
Don't include @ symbol in role names

Example:

✅ Correct: /setup-roles roles:"🎮:Gaming"
❌ Wrong: /setup-roles roles:"🎮:@Gaming"

"Invalid format" or "Parse error"

Common Issues:

Missing commas between roles
Wrong category format
Invalid emoji or role format

Correct Format:

✅ Basic: "🎮:Gaming,📚:Books,🎵:Music"
✅ Categories: "#Gaming\n🎮:PC,🎮:Console\n#Other\n📚:Books"

Reactions Missing

Symptoms: Emoji reactions don't appear or disappear

Use Unicode Emojis

Custom server emojis might not work in all situations
Stick to standard Unicode emojis (🎮📚🎵) for best results

Refresh Reactions

Contact support to refresh reactions for a specific message

This fixes most reaction-related issues

Check Bot Permissions

Bot needs "Add Reactions" permission
Bot needs "Manage Messages" permission
Check channel-specific permissions

Best Practices:

Keep your bot's role high in the role list for fewer issues
Review permissions after adding new bots or roles
Test changes in a private channel before rolling out
Bookmark the FAQ and Common Issues pages

Permission Troubleshooting

Required Bot Permissions

Use Slash Commands

Required for all commands

Manage Roles

Needed to assign and remove roles

Add Reactions

Needed to add emoji reactions to messages

Send Messages

Needed to reply to commands and errors

Manage Messages

Needed to remove reactions if required

Setting Up Permissions

During Bot Invite

Use the official invite link
Make sure all required permissions are selected
Don't modify permissions during invite

After Bot Invite

Go to Server Settings > Roles
Find the bot's role
Click "Permissions" tab
Enable required permissions

Channel-Specific Permissions

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

Getting Help

Before Asking for Help

Please try these steps first:

Check this troubleshooting guide
Review the FAQ
Look at Common Issues
Test with a simple role message first

How to Get Support

📖 Documentation

Check our comprehensive guides and examples

❓ FAQ Section

Quick answers to frequently asked questions

💬 Support Server

Join our Discord server for live help

🐛 Bug Reports

Report bugs through GitHub issues

Information to Include

When asking for help, please provide:

What you're trying to do
What command you used (exact command)
What error you got (exact error message)
Your server setup (role hierarchy, permissions)
Steps you've already tried

Prevention Tips

Setup Best Practices

Start Simple

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

Check Before Adding More

Verify basic setup works
Test role assignment with reactions
Confirm bot permissions are correct

Plan Role Hierarchy

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

Maintenance

Regular Permission Checks: Verify bot permissions haven't changed
Test After Changes: Test role assignment when adding new roles
Monitor for Issues: Check for broken reactions or assignment problems
Keep Documentation Handy: Bookmark this troubleshooting guide

Still need help? Check out the FAQ for more specific questions, or join our support server for community assistance!