Skip to main content

Troubleshooting Guide

Having problems with RoleLogic? This guide covers common issues and their solutions. Work through the checklist first, then find your specific issue below.

Quick Diagnosis Checklist​

Before diving into specific issues, run through this checklist:

  • Is RoleLogic online and in your server?
  • Does RoleLogic have "Manage Roles" permission?
  • Is RoleLogic's role above the roles it needs to manage?
  • Is the rule enabled (not disabled or stopped)?
  • Does the condition actually match the member's roles?
  • Have you tested the rule in the sandbox?
  • Was the rule saved at least 10 seconds ago? (debounce delay)

If all boxes are checked and you still have issues, continue below.

Rules Not Triggering​

Symptom: Rule Exists But Nothing Happens​

Work through these checks in order:

Check 1: Is the rule enabled?

Look at the rule status in the dashboard:

  • Enabled (green) = Active and processing
  • Disabled (gray) = Saved but not running
  • Stopped (red) = Auto-stopped due to conflicts

Solution: If disabled, toggle the rule ON. If stopped, see Rule Automatically Stopped.

Check 2: Wait for the debounce period

RoleLogic batches rapid changes with a 10-second debounce. If you're testing:

Solution: Wait at least 10 seconds after a role change, then check if the rule fired.

Check 3: Does the condition actually match?

Your condition might not match the member's roles as you expect.

Solution:

  1. Open the Testing Sandbox
  2. Select the exact roles the member has (including @everyone!)
  3. Click "Run Test"
  4. See if your rule shows in the results

If it doesn't match in the sandbox, review your condition settings.

Check 4: Is there a role hierarchy issue?

RoleLogic might match the condition but fail to apply the action.

Solution: In Discord Server Settings → Roles, verify:

  • RoleLogic's role is ABOVE all roles in your action
  • No role overrides are blocking the bot
  • The bot hasn't been kicked and re-invited (check role exists)

Check 5: Is another system interfering?

Another bot, moderator, or Discord feature might be changing roles simultaneously.

Solution:

  1. Check Activity Log for recent changes
  2. Review other bots' role-management features
  3. Check if a moderator is manually changing roles
  4. Look for Discord integrations affecting roles

Symptom: Rule Works for Some Members But Not Others​

Cause 1: Partial role hierarchy

RoleLogic can manage some roles but not others due to hierarchy.

Solution: Check that RoleLogic's role is above ALL roles in your rule's actions, not just some.

Cause 2: Cross-server rule, member not in both servers

For cross-server actions, the member must exist in both servers.

Solution: Verify the member is in the target server. Cross-server rules silently skip members who aren't in both servers.

Cause 3: Member has unusual role combination

The member might have roles that cause a different condition to match first.

Solution: Test in the sandbox with the member's exact role combination.

Symptom: Rule Triggers But Changes Revert​

Cause: Another system is reverting RoleLogic's changes.

Common culprits:

  • Another bot managing the same roles
  • A moderator manually reverting changes
  • Discord integration removing roles
  • Another RoleLogic rule with conflicting logic

Solution:

  1. Identify what's reverting the changes (check all role logs)
  2. Coordinate with other bots to avoid conflicts
  3. Review your rules for internal conflicts
  4. If needed, disable competing systems

Permission Errors​

"Cannot Manage This Role"​

Cause: The target role is above RoleLogic's role in the hierarchy.

Solution:

  1. Open Discord Server Settings → Roles
  2. Find the "RoleLogic" role
  3. Click and drag it ABOVE the role causing the error
  4. Save changes

Tip: Position RoleLogic above all roles you want it to manage, but below Admin/Owner roles for security.

"Missing Permissions" or "Manage Roles Required"​

Cause: RoleLogic doesn't have the Manage Roles permission.

Solution:

  1. Go to Discord Server Settings → Roles
  2. Click the "RoleLogic" role
  3. Scroll to Permissions
  4. Enable "Manage Roles"
  5. Save changes

"No Webhook Perms" (For Logging)​

Cause: RoleLogic can't create webhooks in the logging channel.

Solution:

  1. Go to the logging channel in Discord
  2. Click Edit Channel → Permissions
  3. Add RoleLogic or the RoleLogic role
  4. Enable "Manage Webhooks"
  5. Save changes

Unexpected Behavior​

Symptom: Wrong Roles Being Added/Removed​

Cause 1: Another rule is interfering

Multiple rules can affect the same member.

Solution:

  1. Review ALL rules that could apply to this member
  2. Check rule priorities (lower numbers run first)
  3. Test in sandbox to see the complete cascade
  4. Adjust priorities or conditions to get desired behavior

Cause 2: Rule cascade producing unexpected results

One rule's action might trigger another rule.

Example cascade:

  1. Member gets "Premium"
  2. Rule A fires: "If Premium → add VIP"
  3. Member now has VIP
  4. Rule B fires: "If VIP → add Lounge Access"
  5. Member now has Lounge Access (might be unexpected!)

Solution:

  1. Use the sandbox to see the full cascade
  2. Adjust priorities if needed
  3. Add conditions to prevent unwanted triggers

Symptom: Roles Keep Flipping Back and Forth​

Cause: Two rules (or a rule and another bot) are fighting.

Example conflict:

  • RoleLogic Rule: "If has A → add B"
  • Other Bot: Removes B when it sees it

Solution:

  1. Identify both systems changing the role
  2. Decide which one should control that role
  3. Disable the other system's control over that role
  4. Or redesign your rules to avoid the conflict

Symptom: Rule Automatically Stopped​

Cause: RoleLogic detected a conflict pattern.

RoleLogic's safety system stops rules when it detects 100+ reverted actions within 1 hour. This indicates something is fighting the rule.

Common causes:

  • Another bot reverting RoleLogic's changes
  • A moderator manually undoing changes
  • Two conflicting RoleLogic rules
  • Discord integration conflicting with the rule

Solution:

  1. Check the Activity Log for "Stopped" status
  2. Identify what's reverting the changes
  3. Fix the underlying conflict
  4. Re-enable the rule from the dashboard

Prevention: Use the sandbox to verify rules work harmoniously before enabling.

Timing and Performance​

Symptom: Role Changes Are Delayed​

Normal behavior: RoleLogic has built-in timing features:

FeatureTimingPurpose
Debounce10 secondsBatches rapid changes
Real-time processingInstantResponds to role changes
Background syncEvery 10 minutesCatches missed changes
New rule activationWithin 1 hourFull propagation

If delays exceed these:

  1. Check Discord status at status.discord.com
  2. Verify RoleLogic is online (check the bot's presence in your server)
  3. Review rate limiting (20 requests per 30 seconds max)

Solution for persistent delays:

  • Simplify complex rule chains
  • Reduce the number of roles per action
  • Wait for Discord API to stabilize

Symptom: Not All Members Updated​

Cause 1: Large server, still processing

For servers with many members, initial sync takes time:

  • 1,000 members: Seconds
  • 10,000 members: Minutes
  • 50,000+ members: May take longer

Solution: Be patient. Check the dashboard periodically to monitor progress.

Cause 2: Background sync not yet run

The background sync runs every 10 minutes.

Solution: Wait up to 10 minutes for the next sync cycle, or manually trigger a role change on a test member.

Dashboard Issues​

Symptom: Can't See My Server​

Cause 1: Missing permissions

You need Administrator or Manage Roles permission to manage a server.

Solution: Ask the server owner to grant you the necessary permissions.

Cause 2: RoleLogic not in server

RoleLogic must be invited before you can manage it.

Solution: Click "Add to Discord" and invite RoleLogic to your server.

Cause 3: OAuth scope issues

Your dashboard login might not have the right Discord permissions.

Solution:

  1. Log out of the dashboard
  2. Clear browser cache/cookies for the dashboard
  3. Log in again with Discord
  4. Make sure to approve the permission request

Symptom: Roles Not Showing in Selector​

Cause 1: Cache needs refresh

The role list might be stale.

Solution: Refresh the page or close and reopen the rule editor.

Cause 2: Role hierarchy hides options

Some roles above RoleLogic won't appear since they can't be managed.

Solution: First fix role hierarchy, then roles should appear.

Symptom: Changes Not Saving​

Cause 1: Session expired

Dashboard sessions expire after 7 days.

Solution: Log out and log back in.

Cause 2: Network issue

Connection problems prevent saving.

Solution: Check internet connection, then try again.

Cause 3: Quota limit reached

You can't save new rules if at quota limit.

Solution: Delete unused rules or upgrade your plan.

Cross-Server Issues​

"Bot and User Not in Guild"​

Cause: For cross-server actions, both conditions must be met:

  1. RoleLogic must be in the target server
  2. The member must be in the target server

Solution:

  1. Verify RoleLogic is invited to the target server
  2. Confirm the member exists in the target server
  3. Check that RoleLogic has proper permissions in both servers

Cross-Server Actions Not Working​

Cause: Permission or hierarchy issues in the TARGET server.

Solution:

  1. Go to the TARGET server's settings (not source)
  2. Position RoleLogic's role correctly
  3. Verify "Manage Roles" permission
  4. Test that RoleLogic can manually assign roles in that server

Cross-Server Linked Server Limit​

Cause: Free plan allows 5 linked servers.

Solution:

  • Remove unused cross-server actions, OR
  • Upgrade to premium for expanded capacity

Getting More Help​

Diagnostic Steps​

  1. Check Activity Log — See recent configuration changes
  2. Test in Sandbox — Isolate rule behavior
  3. Review Webhook Logs — Check for error messages
  4. Check Discord Status — Verify Discord isn't having issues

Contact Support​

If you've tried everything:

  1. Gather information:

    • Server ID (if comfortable sharing)
    • Rule configuration
    • Error messages (exact text)
    • Screenshots of the issue

  2. Document what you've tried:

    • Which troubleshooting steps you followed
    • What changed (if anything)

  3. Visit the support server:

    • See Support page for details
    • Be specific about your issue
    • Be patient for responses

Prevention Tips​

Test Before Going Live​

Always use the sandbox before enabling new rules, especially those affecting:

  • High-member-count roles
  • Staff or admin roles
  • Multiple roles at once

Start Simple​

Begin with basic rules. Add complexity gradually after confirming each step works.

Monitor After Changes​

After modifying rules:

  1. Test on a few members manually
  2. Watch the Activity Log for issues
  3. Check webhook notifications
  4. Be ready to disable rules if problems occur

Document Your Logic​

Keep notes about:

  • Why each rule exists
  • What it's supposed to do
  • Any dependencies on other rules

Regular Reviews​

Periodically (monthly) review your rules:

  • Remove obsolete rules
  • Update rules for new roles
  • Check for optimization opportunities
  • Verify everything still works as expected