Troubleshooting Access

If a member is not getting the access they expect, follow this structured troubleshooting flow.

Step 1 - Check Bot Status

1. Go to Creator Dashboard > Settings > Integrations > Discord.
2. Confirm the status reads Connected and your server name is displayed.
3. If the status shows Disconnected or Error, click Reconnect and re-authorize the bot.

tip

After reconnecting, allow up to two minutes for the bot to re-establish its session with Discord. PayBru runs a health check every 30 minutes that verifies bot permissions and cleans up stale data, so connection issues are usually detected automatically.

Step 2 - Verify the Member's Account Link

The member must have linked their Discord account to PayBru via OAuth:

1. Ask the member to visit their PayBru Profile > Connected Accounts.
2. They should see their Discord username listed. If not, they need to click Connect Discord and authorize via OAuth2.
3. Once connected, their Discord user ID is stored in their PayBru user claims and used for role assignment.

info

If a member changes their Discord account, they must re-link the new account on PayBru. The old link is not updated automatically.

Step 3 - Verify Role Mapping

1. On the dashboard, go to Integrations > Discord > Role Mappings.
2. Confirm that the member's current tier has an active mapping (IsActive = true) to a Discord role.
3. Confirm the mapped Discord role still exists in your server. If the role was deleted in Discord, you will need to create a new one and update the mapping.
4. Check the RemoveOnTierLoss setting - if the member previously had a role that was removed, it may be because this flag is set to true.

Step 4 - Check the Sync Log

PayBru keeps a log of every role change attempt:

1. Go to Integrations > Discord > Sync Log.
2. Search for the member's name or Discord ID.
3. Look for recent entries. Each entry shows:
   • Timestamp - when the event occurred.
   • Action - role added or removed.
   • Status - success, failed, or pending.
   • Error detail - if the action failed, the reason is shown here (e.g., "Missing Permissions", "Unknown Role").

Common error messages and what they mean:

Error	Meaning	Action
Missing Permissions	The bot lacks required permissions (ManageRoles, ViewAuditLog, etc.) or the role is above it in hierarchy.	Check all 6 required permissions and move the PayBru role higher in Server Settings > Roles.
Unknown Role	The mapped Discord role has been deleted.	Create the role again or update the mapping.
Unknown Member	The user is not in the server. PayBru checks guild membership via the REST API with a 5-minute cache.	Ask the member to join the server first.
Rate Limited	Discord is throttling requests. PayBru uses a 50ms delay between assignments to avoid this.	Wait for the next 5-minute sync cycle to retry.

Step 5 - Check Sync Timing

If the member's role has not appeared yet, keep these sync intervals in mind:

Service	Interval
Role sync (reconciliation)	Every 5 minutes
Member count sync	Every 30 minutes
Ban sync	Every 5 minutes
Health check	Every 30 minutes
Membership expiry check	Every 1 hour

For a new subscription, the role should appear within seconds. If it does not, the 5-minute background sync will catch it. If the member's payment failed, the 3-day grace period keeps roles active - after that, the hourly expiry check removes them.

Step 6 - Run a Manual Resync

If the sync log shows no recent attempt for the member:

1. Go to Integrations > Discord.
2. Click Resync All Members for a full reconciliation, or search for the specific member and click Resync next to their name.
3. Wait for the sync to complete. A progress indicator shows the current status.

caution

Full resyncs on servers with more than 1 000 members can take several minutes due to the 50ms delay between role assignments to respect Discord rate limits. Disconnected servers are skipped gracefully.

Step 7 - Test with a Fresh Account

If the issue persists and you cannot identify the cause:

1. Create a secondary Discord account (or ask a trusted member to help).
2. Link it to a test PayBru account.
3. Subscribe to the affected tier.
4. Check whether the role is assigned correctly.

This helps determine whether the problem is account-specific or system-wide.

Step 8 - Contact Support

If none of the above steps resolve the issue:

1. Gather the following information:
   • Your PayBru creator page URL.
   • The affected member's PayBru username and Discord ID.
   • Screenshots of the sync log entries.
   • The Discord role name and tier name involved.
2. Open a support ticket at support.paybru.co.za or email support@paybru.co.za.
3. Include all gathered details so the team can investigate without back-and-forth.

tip

You can find a Discord user's ID by enabling Developer Mode in Discord (Settings > Advanced > Developer Mode), then right-clicking the user and selecting Copy User ID.

Health Check Notifications

PayBru's automated health check runs every 30 minutes and notifies community owners when permissions are missing. There is a 7-day grace period before the first notification, so you will not be alerted for brief, transient permission changes.