Skip to main content

Common Discord Sync Issues

Most sync issues fall into a handful of categories. Start with the matching section below.

Bot Permission Errors​

Symptom: You see a "Missing Permissions" warning or roles are not assigned.

Fix:

  1. Open Server Settings > Roles in Discord.
  2. Click the PayBru bot role.
  3. Confirm the bot has the permissions it needs to manage roles.
  4. Check that channel overrides do not block the bot.
caution

If you revoke the bot's permissions and re-grant them, you may need to reconnect the integration from Settings > Integrations > Connection.

Role Hierarchy Problems​

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

Cause: Discord requires the bot's role to sit above every role it needs to manage.

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 is rate limiting role changes.
  • Payment confirmation is still settling.
  • The next role sync has not run yet.

If the delay exceeds 10 minutes, refresh Settings > Integrations > Connection and check again after the next sync.

Members Not Getting Roles​

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

Checklist:

  1. The member linked Discord on their PayBru profile.
  2. The member joined your Discord server.
  3. The tier is mapped to the correct role in Tiers.
  4. The subscription is still active in Members.

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 tier's Discord role setting was deleted or changed.
  • The member was downgraded, cancelled, or moved to a tier with a different Discord role.

Check the member's status in Members and the connected server status in Settings > Integrations > Connection.

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.
  • 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. As long as Settings > Integrations > Connection shows Connected, role management is active.

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

Error Handling​

PayBru handles sync errors as follows:

  • If a role update fails, the next scheduled sync cycle (every 5 minutes) will check again.
  • If one member's role assignment fails, PayBru continues processing the remaining members.
  • Disconnected servers are skipped until the integration is reconnected.

See also: