---
title: "Troubleshooting - PayBot Documentation"
description: "Solve common issues with setup, payments, roles, and server configuration. Comprehensive troubleshooting guide for PayBot Discord server administrators."
canonical: https://paybotapp.com/docs/troubleshooting/
source: /docs/troubleshooting/
---

[Home](https://paybotapp.com/) / [Docs](https://paybotapp.com/docs/) / Troubleshooting

# Troubleshooting

Solve common issues with setup, payments, roles, and server configuration

## Table of Contents

-   [Setup & Connection Issues](#setup-issues)
-   [Payment & Subscription Issues](#payment-issues)
-   [Role Assignment Issues](#role-issues)
-   [Bot & Permission Issues](#bot-issues)
-   [Subscription Management Issues](#subscription-issues)
-   [Getting Additional Help](#getting-help)

## Setup & Connection Issues

Common problems encountered during initial PayBot setup and Stripe account connection.

"Connection Failed" Error

#### Possible Causes

-   Stripe account is restricted or requires verification
-   OAuth authorization was cancelled or failed
-   Network connectivity issues during connection
-   Stripe account not properly configured for Connect

#### Solutions

1.  Check your Stripe dashboard for account restrictions or verification requirements
2.  Try the connection process again, ensuring you complete the full OAuth flow
3.  Verify your Stripe account is in a supported country/region
4.  Contact Stripe support if your account is restricted

"Verification Failed" After Connection

#### Possible Causes

-   Webhook endpoint issues
-   Network connectivity problems
-   Stripe API key configuration issues
-   Account permissions insufficient

#### Solutions

1.  Wait 2-3 minutes and try "🔍 Verify Connection" again
2.  Check your internet connection and try again
3.  Ensure your Stripe account has proper permissions enabled
4.  Contact support if verification consistently fails

Cannot Access /setup Command

#### Possible Causes

-   Bot not properly added to server
-   Missing Administrator permissions
-   Bot offline or experiencing issues

#### Solutions

1.  Ensure PayBot is added to your server with proper permissions
2.  Verify you have Administrator permissions in the server
3.  Check if PayBot appears online in the member list
4.  Try reinviting the bot if issues persist

Stripe Dashboard Shows "Application Not Connected"

#### Possible Causes

-   Incomplete OAuth flow
-   Webhook delivery failures
-   Account configuration issues

#### Solutions

1.  Reconnect your Stripe account through /setup
2.  Check Stripe webhook settings in your dashboard
3.  Ensure your account is properly configured for Connect
4.  Contact Stripe support for account-specific issues

## Payment & Subscription Issues

Problems related to payment processing, subscription creation, and billing.

Members Can't Complete Payment

#### Possible Causes

-   Server reached subscriber limit for current plan
-   Membership tier is archived or inactive
-   Stripe account issues or restrictions
-   Payment method problems

#### Solutions

1.  Use `/setup` and click "🔍 Verify Connection"
2.  Check your current plan limits in `/setup`
3.  Ensure the membership tier is not archived
4.  Check Stripe dashboard for account issues
5.  Upgrade your PayBot plan if you've reached subscriber limits

"One-Time Payments Not Available"

#### Possible Causes

-   Not subscribed to Large plan ($89/month)
-   Feature not enabled for your account
-   Plan upgrade not yet processed

#### Solutions

1.  Check your current PayBot plan in `/setup`
2.  Upgrade to Large plan using `/setup → Upgrade PayBot Plan`
3.  Wait a few minutes after upgrading for features to activate
4.  Contact support if you have Large plan but feature isn't available

Failed Recurring Payments

#### Possible Causes

-   Member's payment method expired
-   Insufficient funds
-   Card declined by bank
-   Stripe account issues

#### Solutions

1.  Check Stripe Dashboard for failed payment details
2.  Contact the member to update their payment method
3.  Members can update payment method through Stripe customer portal
4.  Monitor Stripe for retry attempts and outcomes

Prorated Billing Issues

#### Possible Causes

-   Complex subscription changes
-   Timing of subscription modifications
-   Currency conversion issues

#### Solutions

1.  Check Stripe Dashboard for detailed billing information
2.  Contact Stripe support for complex proration issues
3.  Ensure subscription changes happen at appropriate times
4.  Verify currency settings are correct

## Role Assignment Issues

Problems with Discord roles not being assigned, removed, or updated correctly.

Roles Not Being Assigned

#### Most Common Cause

PayBot's role is below membership roles in Discord's role hierarchy

#### Solution

1.  Go to **Server Settings > Roles**
2.  Find PayBot's role in the hierarchy list
3.  Drag PayBot's role above all membership roles
4.  Test with a new subscription

**Critical:** PayBot must be above membership roles to assign them. Correct order: `PayBot > Premium Role > Basic Role > @everyone`

Bot Lacks "Manage Roles" Permission

#### Symptoms

-   Error messages about insufficient permissions
-   Roles not being assigned or removed
-   Bot cannot modify member roles

#### Solutions

1.  Go to **Server Settings > Roles**
2.  Ensure PayBot has "Manage Roles" permission enabled
3.  Check that the permission is enabled for the channels where commands are used
4.  Reinvite PayBot with correct permissions if needed

Role Deleted or Renamed

#### Symptoms

-   Subscribers not receiving roles
-   Error messages about missing roles
-   Role assignment failures

#### Solutions

1.  Recreate the missing Discord role with the same name
2.  In `/setup → Manage Pricing → Edit`, click "Change Role"
3.  Select the recreated role from the dropdown
4.  Test role assignment with a new subscription

Subscribers Keep Old Roles After Cancellation

#### Possible Causes

-   Role hierarchy issues
-   Bot temporarily offline during cancellation
-   Discord API delays

#### Solutions

1.  Check that role hierarchy is still correct
2.  Manually remove roles from affected members if needed
3.  Wait a few minutes for Discord API synchronization
4.  Contact support if issue affects many members

## Bot & Permission Issues

Problems with bot functionality, permissions, and Discord integration.

Bot Shows Offline

#### Possible Causes

-   Temporary Discord API issues
-   Bot server maintenance
-   Network connectivity problems
-   Bot token issues

#### Solutions

1.  Wait 5-10 minutes and check again
2.  Check Discord's status page for API issues
3.  Verify bot token is still valid
4.  Contact support if bot remains offline for extended period

Commands Not Responding

#### Possible Causes

-   Bot lacks required permissions
-   Channel permission restrictions
-   Command cooldowns or rate limits
-   Bot server overload

#### Solutions

1.  Ensure bot has all required permissions
2.  Check channel-specific permissions
3.  Try the command in a different channel
4.  Wait a minute and try again

Missing Bot Permissions

#### Required Permissions

-   Manage Roles - For automatic role assignment
-   Send Messages - To respond to commands
-   Use Slash Commands - For /setup and /subscription
-   Embed Links - For rich embeds in responses
-   Read Message History - For context in threads

#### Solutions

1.  Go to Server Settings > Roles
2.  Find PayBot's role and enable missing permissions
3.  Ensure permissions are enabled for the specific channels
4.  Reinvite the bot if permissions cannot be corrected

Bot Not in Server

#### Possible Causes

-   Bot was kicked or banned
-   Server ownership changed
-   Bot token invalidated

#### Solutions

1.  Check if PayBot appears in the server member list
2.  Use the invitation link to re-add the bot
3.  Ensure you're the server owner or have Administrator permissions
4.  Contact support if re-invitation fails

## Subscription Management Issues

Problems with subscription status, member management, and ongoing subscription operations.

Members Can't Cancel Subscriptions

#### Possible Causes

-   Bot lacks proper permissions
-   Subscription not found in Stripe
-   Database synchronization issues

#### Solutions

1.  Verify bot has "Manage Roles" permission
2.  Check Stripe Dashboard for subscription status
3.  Contact support for database sync issues
4.  Have member cancel directly in Stripe if bot method fails

Subscription Status Not Updating

#### Possible Causes

-   Webhook delivery failures
-   Network connectivity issues
-   Stripe API problems
-   Database connection issues

#### Solutions

1.  Check Stripe webhooks in your dashboard
2.  Verify webhook endpoint is accessible
3.  Contact support for webhook configuration help
4.  Monitor Stripe events for delivery failures

Double-Charging Issues

#### Possible Causes

-   Multiple subscription records
-   Failed cancellation attempts
-   Webhook processing duplicates

#### Solutions

1.  Check Stripe Dashboard for duplicate subscriptions
2.  Contact support to identify and resolve duplicates
3.  Review payment history for any anomalies
4.  Request refunds for any erroneous charges

Plan Limit Reached

#### Possible Causes

-   Server has reached subscriber limit for current plan
-   Plan upgrade not yet processed
-   Database not updated with new limits

#### Solutions

1.  Check current plan and limits in `/setup`
2.  Upgrade to higher plan if needed
3.  Wait for plan upgrade to process (may take a few minutes)
4.  Contact support if limits don't update after upgrade

## Getting Additional Help

When troubleshooting steps don't resolve your issue, here's how to get additional support.

### 📚 Documentation

Comprehensive guides for all PayBot features

-   Setup and configuration guides
-   Feature explanations and examples
-   Best practices and tips

[Browse Documentation](https://paybotapp.com/docs/)

### 💬 Community Support

Get help from other server administrators

-   Ask questions and share experiences
-   Learn from community solutions
-   Connect with other PayBot users

[Join Discord Server](https://discord.gg/paybotapp)

### 🎫 Direct Support

Personalized help from the PayBot team

-   Account-specific issues
-   Complex configuration problems
-   Bug reports and feature requests

[Contact Support](https://discord.gg/paybotapp)

#### Before Contacting Support

To help us assist you more effectively, please prepare:

-   Your server ID and bot's role ID
-   Description of the issue and steps to reproduce
-   Any error messages you've received
-   What troubleshooting steps you've already tried
-   Your current PayBot plan and Stripe account status

[Tier Groups & Upgrades](https://paybotapp.com/docs/tier-groups/) [Back to Documentation](https://paybotapp.com/docs/)