Troubleshooting

Use this page when something does not behave the way a server owner or member expects.

Bot cannot grant roles

Most role failures come from Discord permissions or role hierarchy.

Check:

• The Arcalotl bot has Manage Roles.
• The Arcalotl bot role is above every paid role it needs to grant.
• The selected role is not @everyone.
• The role still exists in Discord.

After fixing role hierarchy, ask the member to retry checkout or contact support if Stripe already confirmed the subscription.

Stripe is not connected

If commands say there is no payment gateway, run:

/retain setup

Complete Stripe Connect onboarding. Arcalotl can create Checkout Sessions only after the server has an active payment provider configuration.

Checkout link fails

Check:

• Stripe Connect setup is complete.
• The plan is active.
• The Stripe price exists in the connected account.
• The member chose a current plan from /subscribe or the subscribe channel.

If the plan was deleted or archived, create or import a new active plan.

Member paid but role was not granted

Check:

• Stripe shows the subscription as active or trialing.
• The bot can manage the paid role.
• The subscription is attached to the expected Discord member.
• The plan still has the Discord role mapping.

Arcalotl grants roles from Stripe subscription events. If Stripe is active and the bot can manage the role, support can inspect the activity feed and event log.

Payment recovery DM failed

Payment recovery tries a DM first. If Discord rejects the DM, Arcalotl tries to create a private payment-help channel.

Check:

• The bot can create channels.
• The bot can view and send messages in the server.
• The server has not blocked channel creation for the bot role.

If the private channel cannot be created, the recovery attempt is marked sent to avoid a stuck loop. The member can still use /manage to open Stripe Billing Portal.

Private payment-help channel was not created

The private fallback channel is best effort. It needs Discord channel permissions to succeed.

Check:

• Create Channels permission
• View Channels permission
• Send Messages permission
• No server-level permission overwrite blocks the bot

The channel is deleted when payment recovery is resolved or exhausted.

Annual offer not appearing

Term optimization requires:

• Active monthly subscription
• Minimum tenure met, default 90 days
• No active payment recovery sequence
• Post-dunning cooldown complete, default 30 days
• No recent term optimization offer inside the cooldown, default 180 days
• Annual billing option on the same tier
• Annual price lower than 12 monthly payments

If any of those checks fail, Arcalotl skips the offer.

Cancel save not appearing

Cancel saves are based on the selected cancellation reason and the server's retention settings.

Check:

• Cancel saves are enabled.
• The reason maps to an offer.
• Discount and downgrade offers meet the tenure threshold, default 14 days.
• Downgrade has a configured downgrade plan.
• The subscription has not accepted a save offer inside the repeat cooldown, default 180 days.

By default, switching and other do not show a save offer.

Dashboard access denied

Sign in with Discord and choose a server where you have access. Admin access can come from server permissions or Arcalotl's configured admin list.

If access was recently changed, sign out and sign in again.