Skip to main content

Common Discord Sync Issues

Most sync issues fall into a handful of categories. Work through the relevant section below before reaching out to support.

Bot Permission Errors​

Symptom: PayBru logs show "Missing Permissions" or roles are not assigned.

Fix:

  1. Open Server Settings > Roles in Discord.
  2. Click the PayBru bot role.
  3. Confirm the following permissions are enabled: ManageRoles, ViewAuditLog, BanMembers, ManageChannels, SendMessages, EmbedLinks.
  4. If you use channel-specific permission overrides, make sure none of them deny the bot's access.
caution

If you revoke the bot's permissions and re-grant them, you may need to reconnect the integration from your PayBru dashboard.

Role Hierarchy Problems​

Symptom: The bot can assign some roles but not others.

Cause: Discord requires a bot's role to be higher in the role list than any role it tries to assign. If you added a new tier role above the PayBru bot role, the bot cannot manage it.

Fix:

  1. Go to Server Settings > Roles.
  2. Drag the PayBru role above every role it needs to manage.
  3. Click Save Changes.

Delayed Sync​

Symptom: A member subscribes but their role appears minutes later instead of instantly.

Possible causes:

  • Discord API rate limits. During busy periods, Discord throttles API calls. PayBru inserts a 50ms delay between individual role assignments to stay within limits, which can add up on large servers.
  • Webhook delivery delay. Payment processor webhooks occasionally lag by a few seconds to a few minutes.
  • Background reconciliation pending. If the real-time event was missed, the role will be corrected during the next 5-minute role sync cycle.

If the delay exceeds 10 minutes, try a manual resync from the dashboard.

Members Not Getting Roles​

Symptom: A member has an active subscription but no Discord role.

Checklist:

  1. Has the member linked their Discord account? Members must connect their Discord account via OAuth on their PayBru profile. If they have not, PayBru cannot identify them in your server.
  2. Is the member in your server? PayBru checks guild membership via the Discord REST API (with a 5-minute cache) before assigning roles. The member must have already joined the server. Share your server invite link on your PayBru page.
  3. Is the role mapping configured and active? Check Creator Dashboard > Settings > Integrations > Discord > Role Mappings and confirm the member's tier has an active mapping (IsActive = true).
  4. Is the subscription active? Verify the member's status under Creator Dashboard > Members. A failed payment may have moved them to PastDue or Ended status.

Roles Removed Unexpectedly​

Symptom: A member loses their role even though they are still subscribed.

Possible causes:

  • A server moderator manually removed the role. PayBru will reassign it during the next 5-minute role sync.
  • The member's payment failed and the 3-day grace period expired.
  • The role mapping was deleted, deactivated, or changed.
  • The mapping has RemoveOnTierLoss=true and the member was downgraded or cancelled.
Sticky Roles

If you do not want a role to be removed on cancellation or downgrade, set RemoveOnTierLoss = false on the mapping. See Role Mapping Basics for details.

Check the Sync Log on your dashboard for a detailed event history.

Health Check and Permission Monitoring​

PayBru runs an automated health check every 30 minutes that:

  • Verifies the bot still has the required permissions in your server.
  • Detects missing permissions (ManageRoles, ViewAuditLog, BanMembers, ManageChannels, SendMessages, EmbedLinks).
  • Cleans up stale data from disconnected servers.

If the health check detects a problem, PayBru notifies the community owner. There is a 7-day grace period before the first notification is sent, so transient issues (like brief permission changes during server reorganization) will not trigger alerts immediately.

tip

If you receive a health check notification, review your bot's permissions in Server Settings > Roles and ensure the PayBru role has all required permissions enabled.

Bot Appears Offline​

Symptom: The PayBru bot shows as offline in the member list.

The bot does not need to appear online to function. PayBru manages roles via API calls, not through a persistent bot presence. As long as the integration shows Connected on your dashboard, role management is active.

If the dashboard shows Disconnected, re-authorize the bot by clicking Reconnect in your integration settings.

Error Handling​

PayBru handles sync errors as follows:

  • Sync failures are logged but there is no automatic retry mechanism. The next scheduled sync cycle (every 5 minutes) will attempt the operation again.
  • Partial failures are allowed: if one member's role assignment fails, PayBru continues processing the remaining members rather than stopping the entire sync.
  • Disconnected servers are skipped gracefully, without blocking sync for other communities.