Skip to main content

Discord Bot Troubleshooting

Common issues and solutions for the Loyalteez Discord bot integration.

Setup Issues​

Bot Not Responding​

Symptoms:

  • Bot doesn't respond to commands
  • Slash commands not appearing
  • Bot appears offline

Possible Causes:

  1. Bot not added to server
  2. Bot lacks required permissions
  3. Bot token invalid
  4. Cloudflare Worker not deployed

Solutions:

1. Check Bot is Added:

  • Verify bot is in server member list
  • Check bot is online (green status indicator)
  • Try mentioning bot: @Loyalteez Bot

2. Check Bot Permissions:

  • Bot needs these permissions:
    • Send Messages
    • Embed Links
    • Read Message History
    • Use Slash Commands
    • Manage Messages (for admin commands)
  • Re-invite bot with correct permissions if needed

3. Check Slash Commands:

  • Discord caches slash commands (can take up to 1 hour)
  • Try refreshing Discord client (Ctrl+R)
  • Wait for command cache to refresh

4. Verify Deployment:

  • Check Cloudflare Worker is deployed
  • Verify worker logs: wrangler tail
  • Check bot token is configured

/setup Command Not Working​

Symptoms:

  • /setup command doesn't appear
  • Error: "Server required" message
  • Setup command fails

Solutions:

1. Verify Command Availability:

  • Slash commands can take up to 1 hour to appear
  • Refresh Discord client
  • Check bot has proper permissions

2. Check User Permissions:

  • User running /setup must have "Manage Server" permission
  • Verify user role has correct permissions
  • Try running as server owner

3. Verify Brand ID Format:

  • Brand ID must be wallet address format
  • Format: 0x1234567890abcdef1234567890abcdef12345678
  • Must be 42 characters (0x + 40 hex characters)
  • Copy from Partner Portal → Settings → Account

4. Check Command Syntax:

  • Correct: /setup connect brand_id:0x...
  • Ensure brand_id: parameter is included
  • Check for typos or extra spaces

Commands Not Appearing​

Symptoms:

  • Slash commands don't show up
  • Commands missing from command list
  • "Unknown interaction" error

Solutions:

1. Wait for Cache Refresh:

  • Discord caches slash commands
  • Can take up to 1 hour to refresh
  • Refresh Discord client (Ctrl+R)

2. Check Bot Permissions:

  • Bot needs "Use Slash Commands" permission
  • Verify bot has application.commands scope
  • Re-invite bot with correct scopes

3. Check Command Registration:

  • Verify commands are registered with Discord
  • Check worker logs for registration errors
  • Verify bot token is valid

4. Try Re-inviting Bot:

  • Remove bot from server
  • Re-invite with correct permissions and scopes
  • Wait for commands to refresh

Command Issues​

/daily Not Working​

Symptoms:

  • /daily command doesn't respond
  • Error message appears
  • No reward given

Solutions:

1. Check Server Setup:

  • Server must be connected (run /setup connect)
  • Verify setup completed successfully
  • Check server configuration exists

2. Check Cooldown:

  • User may have already checked in today
  • Daily check-in resets at midnight UTC
  • Wait for reset or check previous check-in

3. Check Shared Services:

  • Verify shared services API is accessible
  • Check shared services status
  • Review worker logs for API errors

4. Check Error Messages:

  • Review error message for details
  • Check worker logs: wrangler tail
  • Verify API connection

/balance Shows Zero or Error​

Symptoms:

  • Balance shows 0 LTZ
  • Error message when checking balance
  • Balance not updating

Solutions:

1. Verify User Has Earned LTZ:

  • User must earn LTZ first (via /daily, GM/GN, etc.)
  • Check Partner Portal → Analytics for user activity
  • Wallet is created automatically on first reward

2. Check API Connection:

  • Verify Loyalteez API URL
  • Check API status
  • Review API response codes

3. Wait for Blockchain Confirmation:

  • Transactions require blockchain confirmation
  • Wait a few minutes and check again
  • Verify transaction on block explorer

4. Check User Identifier:

  • Verify user identifier format: discord_{user_id}@loyalteez.app
  • Check Discord user ID is correct
  • Verify identifier matches Partner Portal

/leaderboard Empty or Not Loading​

Symptoms:

  • Leaderboard shows empty
  • Error loading leaderboard
  • Leaderboard not updating

Solutions:

1. Verify Data Exists:

  • Check users have earned LTZ
  • Verify activity exists for selected period
  • Check Partner Portal → Analytics

2. Try Different Filters:

  • Try different metrics: ltz_earned, activity, streak
  • Try different periods: week, month, all
  • Check if data exists for selected filters

3. Check Shared Services:

  • Verify leaderboard API is accessible
  • Check API response
  • Review worker logs for errors

4. Check Time Period:

  • Try "All Time" to see all data
  • Check if data exists for selected period
  • Verify leaderboard is updating

/perks Not Showing Perks​

Symptoms:

  • Perks list is empty
  • Error loading perks
  • Perk purchase fails

Solutions:

1. Check Perk Configuration:

  • Verify perks are created in Partner Portal
  • Ensure perks are active
  • Check perk availability dates

2. Check Shared Services:

  • Verify perks API is accessible
  • Check API response
  • Review worker logs for errors

3. Check Perk Availability:

  • Verify perks are available
  • Check perk supply limits
  • Verify perk is active and not expired

Voice Rewards Not Working​

Symptoms:

  • Voice time not tracking
  • No rewards for voice activity
  • Voice command not working

Solutions:

1. Check Voice Configuration:

  • Verify voice rewards are configured
  • Check voice reward settings: /config voice
  • Verify voice tracking is enabled

2. Check Bot Permissions:

  • Bot needs "View Channels" permission
  • Bot needs "Connect" permission in voice channels
  • Verify bot can see voice channels

3. Check Voice Activity:

  • User must be in voice channel
  • Bot must be able to track voice time
  • Check voice activity is being recorded

4. Check Voice Rewards:

  • Verify voice rewards are configured in Partner Portal
  • Check reward amounts and limits
  • Verify voice events are active

Permission Issues​

"Missing Permissions" Error​

Symptoms:

  • Commands fail with permission error
  • Bot can't perform actions
  • Permission denied messages

Solutions:

1. Check Bot Permissions:

  • Bot needs these permissions:
    • Send Messages
    • Embed Links
    • Read Message History
    • Use Slash Commands
    • Manage Messages
  • Re-invite bot with correct permissions

2. Check Role Hierarchy:

  • Bot role must be above users it interacts with
  • Check server role hierarchy
  • Move bot role higher if needed

3. Check Channel Permissions:

  • Verify bot has permissions in channel
  • Check channel-specific permission overrides
  • Ensure bot can send messages in channel

Admin Commands Not Working​

Symptoms:

  • Admin commands fail
  • "You don't have permission" error
  • Commands not available

Solutions:

1. Check User Permissions:

  • User must have "Manage Server" permission
  • Verify user role has correct permissions
  • Check role hierarchy

2. Check Command Requirements:

  • Some commands require admin permissions
  • Verify command requirements
  • Check command documentation

3. Check Bot Permissions:

  • Bot needs "Manage Messages" for some admin commands
  • Verify bot has required permissions
  • Check bot role hierarchy

Configuration Issues​

/config Not Working​

Symptoms:

  • Config command doesn't respond
  • Configuration not saving
  • Settings not applying

Solutions:

1. Check User Permissions:

  • User must have "Manage Server" permission
  • Verify user is server administrator
  • Check role permissions

2. Check Server Setup:

  • Server must be set up first (run /setup connect)
  • Verify setup completed successfully
  • Check server configuration exists

3. Use Partner Portal:

  • Advanced configuration available in Partner Portal
  • Navigate to Integrations → Discord
  • Configure settings in web interface

Natural Participation Not Working​

Symptoms:

  • GM/GN messages not rewarded
  • Natural participation not detecting
  • No rewards for engagement

Solutions:

1. Check Configuration:

  • Verify natural participation is enabled
  • Check configuration: /config events
  • Verify GM/GN events are active

2. Check Cooldown:

  • User may be on cooldown
  • Default cooldown: 24 hours
  • Wait for cooldown to expire

3. Check Pattern Matching:

  • Supported patterns: gm, good morning, gn, good night
  • Pattern matching is case-insensitive
  • Must be in server messages (not DMs)

4. Check Event Configuration:

  • Verify GM/GN events are configured in Partner Portal
  • Check event reward amounts
  • Verify events are active

Integration Issues​

Third-Party Bot Integration Not Working​

Symptoms:

  • Mee6/Arcane level-ups not rewarding
  • Third-party events not tracking
  • Integration not responding

Solutions:

1. Check Integration Configuration:

  • Verify integration is enabled: /config third-party
  • Check integration settings
  • Verify bot is configured correctly

2. Check Bot Permissions:

  • Integration bot must be in server
  • Verify integration bot has required permissions
  • Check bot is active

3. Check Event Configuration:

  • Verify third-party events are configured in Partner Portal
  • Check event names match integration
  • Verify events are active

4. Check Integration Format:

  • Verify integration data format
  • Check integration webhook format
  • Review integration documentation

Reaction Drops Not Working​

Symptoms:

  • Reaction rewards not triggering
  • Drop events not working
  • Reactions not tracked

Solutions:

1. Check Drop Configuration:

  • Verify drop is created: /drop create
  • Check drop is active
  • Verify drop channel is correct

2. Check Bot Permissions:

  • Bot needs "Read Message History" permission
  • Bot needs "Add Reactions" permission
  • Verify bot can see messages and reactions

3. Check Event Configuration:

  • Verify drop events are configured in Partner Portal
  • Check event reward amounts
  • Verify events are active

Deployment Issues​

Cloudflare Worker Not Deploying​

Symptoms:

  • Worker deployment fails
  • Errors during deployment
  • Worker not accessible

Solutions:

1. Authenticate Wrangler:

wrangler login
wrangler whoami

2. Check Configuration:

  • Verify wrangler.toml is correct
  • Check account_id is set
  • Verify worker name

3. Set Required Secrets:

wrangler secret put DISCORD_BOT_TOKEN
wrangler secret put SUPABASE_PUBLISH_KEY
wrangler secret put SUPABASE_SECRET_KEY

4. Check Build Errors:

  • Review build output
  • Check for syntax errors
  • Verify dependencies are installed

Bot Commands Not Registering​

Symptoms:

  • Commands not appearing in Discord
  • Command registration fails
  • "Unknown interaction" errors

Solutions:

1. Check Bot Token:

  • Verify bot token is correct
  • Get token from Discord Developer Portal
  • Update secret: wrangler secret put DISCORD_BOT_TOKEN

2. Check Application ID:

  • Verify application ID is correct
  • Get from Discord Developer Portal
  • Update in configuration

3. Check Command Registration:

  • Commands are registered on worker startup
  • Check worker logs for registration errors
  • Verify command registration code

4. Wait for Discord Cache:

  • Discord caches commands (up to 1 hour)
  • Refresh Discord client
  • Wait for cache to refresh

Database Issues​

Server Configuration Not Saving​

Symptoms:

  • /setup succeeds but config not persisted
  • Configuration resets
  • Database errors

Solutions:

1. Check Database Connection:

  • Verify Supabase credentials
  • Test database connection
  • Check Supabase dashboard

2. Verify Table Exists:

  • Check discord_server_configs table exists
  • Verify table schema
  • Check table permissions

3. Check Permissions:

  • Verify API keys have write permissions
  • Check RLS policies
  • Verify service role key is used

Performance Issues​

Bot Responding Slowly​

Symptoms:

  • Commands take long to respond
  • Delayed message delivery
  • Timeout errors

Solutions:

1. Check Worker Performance:

  • Review worker logs for slow operations
  • Check API response times
  • Optimize database queries

2. Check API Latency:

  • Verify shared services response times
  • Check blockchain RPC latency
  • Review API logs

3. Check Database Performance:

  • Review database query performance
  • Add indexes if needed
  • Optimize queries

Common Error Messages​

"Server not configured"​

Meaning: Server hasn't been set up with /setup connect.

Solution: Run /setup connect brand_id:0x... as server administrator.

"You don't have permission to use this command"​

Meaning: User lacks required permissions.

Solution: User must have "Manage Server" permission for admin commands.

"Unknown interaction"​

Meaning: Discord interaction timeout or command not registered.

Solution:

  • Wait and try again
  • Refresh Discord client
  • Check bot is online

"Failed to connect server"​

Meaning: Error saving server configuration.

Solution:

  • Check Brand ID format
  • Verify database connection
  • Check Supabase credentials

Debugging Tips​

Enable Logging​

Check Cloudflare Worker logs:

wrangler tail

Check Bot Status​

Verify bot is online in Discord:

  • Check bot appears in server member list
  • Verify bot has green status indicator
  • Try mentioning bot: @Loyalteez Bot

Test API Endpoints​

Test shared services:

curl "https://services.loyalteez.app/streak/status/<brand_id>/discord_<user_id>@loyalteez.app"

Check Database​

Check server configuration:

SELECT * FROM discord_server_configs WHERE server_id = '<server_id>';

Getting Help​

If you're still experiencing issues:

  1. Check Documentation:

  2. Review Logs:

    • Cloudflare Worker logs: wrangler tail
    • Supabase logs: Dashboard → Logs
    • Discord Developer Portal: Bot → Logs

  3. Contact Support:

Need help? [email protected]

Last updated on