Discord Troubleshooting

Discord Troubleshooting

This guide helps you resolve common issues with the Discord Module and provides solutions for various problems you might encounter.

🚨 Common Issues

Bot Not Starting

Symptoms:

• Bot doesn’t appear online in Discord
• Console shows connection errors
• Commands don’t work

Solutions:

1. Check Bot Token

   modules/discord/discord-bot.yml

   bot:
     token: "YOUR_BOT_TOKEN_HERE"  # Make sure this is correct

2. Verify Bot Permissions

   • Ensure bot has proper permissions in Discord
   • Check if bot is banned from server
   • Verify bot is in the correct server

3. Check Network Connection

   • Ensure server has internet access
   • Check firewall settings
   • Verify Discord API is accessible

4. Restart Bot

   /dcbot stop
   /dcbot start

Commands Not Working

Symptoms:

• Slash commands don’t appear in Discord
• Commands show “unknown command” error
• Permission denied errors

Solutions:

1. Check Required Intents

   • Go to Discord Developer Portal → Bot section
   • Verify these intents are ENABLED:
     • ✅ Server Members Intent
     • ✅ Message Content Intent
     • ✅ Guild Members Intent
   • Click “Save Changes” if modified

2. Register Commands

   /dcbot register

   Wait a few minutes for Discord to update

3. Check Permissions

   • Verify role IDs are correct
   • Check if user has required roles
   • Ensure role IDs are not role names

4. Verify Bot Status

   /dcbot status

5. Check Command Cooldowns

   • Wait a moment before retrying
   • Check if command has cooldown period

Intent-Related Issues

Symptoms:

• Bot appears online but commands don’t work
• “Missing Access” errors
• Role checking fails
• Bot can’t access member information

Solutions:

1. Enable Required Intents

   • Go to Discord Developer Portal
   • Select your application
   • Go to “Bot” section
   • Scroll to “Privileged Gateway Intents”
   • Enable these intents:
     • ✅ Server Members Intent
     • ✅ Message Content Intent
     • ✅ Guild Members Intent
   • Click “Save Changes”

2. Restart Bot After Enabling Intents

   /dcbot restart

3. Verify Intent Status

   • Check bot status in Discord Developer Portal
   • Ensure intents show as “Enabled”
   • Wait a few minutes for changes to take effect

Permission Denied Errors

Symptoms:

• “You don’t have permission” messages
• Commands not appearing for some users
• Inconsistent access

Solutions:

1. Check Role Configuration

   modules/discord/discord-bot.yml

   Permissions:
     GetInfo: ["ROLE_ID_1", "ROLE_ID_2"]  # Use actual role IDs

2. Verify Role IDs

   • Use Discord Developer Mode to get role IDs
   • Right-click role → Copy ID
   • Don’t use role names

3. Check Discord Role Hierarchy

   • Ensure roles are in correct order
   • Higher roles have more permissions
   • Check role assignments

4. Test with Administrator Role

   • Users with Administrator permission bypass all checks
   • Use this to test if issue is role-related

Logs Not Appearing

Symptoms:

• No log messages in Discord channels
• Missing event notifications
• Empty log channels

Solutions:

1. Check Channel IDs

   modules/discord/channels.yml

   channels:
     kick_log: "CHANNEL_ID"  # Use actual channel IDs

2. Verify Bot Permissions

   • Bot needs “Send Messages” permission
   • Bot needs “Embed Links” permission
   • Check channel-specific permissions

3. Check Logging Configuration

   modules/discord/channels.yml

   enabled: true  # Make sure logging is enabled

4. Test Logging

   • Perform a test action (kick, ban, etc.)
   • Check if log appears in channel
   • Verify embed formatting

Configuration Errors

Symptoms:

• Bot fails to start
• Configuration validation errors
• Unexpected behavior

Solutions:

1. Validate Configuration

   /dcbot status

2. Check YAML Syntax

   • Ensure proper indentation
   • Check for missing quotes
   • Verify special characters

3. Reload Configuration

   /dcbot reload

4. Reset to Defaults

   • Backup current configuration
   • Delete configuration files
   • Restart server to regenerate

🔧 Debug Mode

Enable Debug Logging

modules/discord/discord-bot.yml

debug:
  enabled: true
  console: true
  file: true
  logging: true

Debug Information

Debug mode provides detailed information about:

• Bot connection status
• Command processing
• Permission checks
• Configuration loading
• Error details

Debug Commands

# Check bot status
/dcbot status

# Reload configuration
/dcbot reload

# Restart bot
/dcbot restart

📊 Performance Issues

High Memory Usage

Symptoms:

• Server lag
• High memory consumption
• Bot becomes unresponsive

Solutions:

1. Restart Bot Regularly

   /dcbot restart

2. Check Command History

   • Clear old command history
   • Limit command history size

3. Monitor Resource Usage

   • Check server performance
   • Monitor memory usage
   • Check for memory leaks

Slow Response Times

Symptoms:

• Commands take long to respond
• Delayed log messages
• Timeout errors

Solutions:

1. Check Network Connection

   • Ensure stable internet connection
   • Check Discord API status
   • Verify server connectivity

2. Optimize Configuration

   • Reduce command cooldowns
   • Limit concurrent operations
   • Check database performance

3. Monitor API Limits

   • Check Discord API rate limits
   • Implement proper rate limiting
   • Monitor API usage

🛠️ Advanced Troubleshooting

Database Issues

Symptoms:

• Commands fail with database errors
• Missing player data
• Inconsistent information

Solutions:

1. Check Database Connection

   • Verify database is running
   • Check connection settings
   • Test database connectivity

2. Verify Data Integrity

   • Check for corrupted data
   • Validate player records
   • Repair database if needed

3. Check Permissions

   • Ensure database user has proper permissions
   • Check table access rights
   • Verify schema integrity

Discord API Issues

Symptoms:

• Bot disconnects frequently
• API rate limit errors
• Inconsistent behavior

Solutions:

1. Check API Status

   • Visit Discord API status page
   • Check for known issues
   • Monitor API response times

2. Implement Rate Limiting

   • Add delays between requests
   • Use proper error handling
   • Implement retry logic

3. Update Dependencies

   • Check for JDA updates
   • Update Discord API version
   • Verify compatibility

📋 Diagnostic Checklist

Pre-Troubleshooting Steps

• Check server console for errors
• Verify bot is online in Discord
• Test basic commands
• Check configuration files
• Verify permissions

Configuration Checklist

• Bot token is correct
• Channel IDs are valid
• Role IDs are correct
• Permissions are properly configured
• Logging is enabled

Network Checklist

• Server has internet access
• Discord API is accessible
• Firewall allows connections
• No proxy issues
• DNS resolution works

🆘 Getting Help

Information to Provide

When seeking help, provide:

1. Error Messages

   • Full error text from console
   • Screenshots of Discord errors
   • Log file excerpts

2. Configuration

   • Relevant configuration sections
   • Permission setup
   • Channel/role IDs (anonymized)

3. Environment

   • Server version
   • Plugin version
   • Discord bot version
   • Operating system

4. Steps to Reproduce

   • What you were doing
   • When the issue occurs
   • How often it happens

Support Channels

• Discord Server: https://discord.gg/2qCMn6KHj4
• Documentation: Check this guide for solutions

Log Files

Enable debug logging and provide:

• Console logs
• Plugin log files
• Discord bot logs
• Error stack traces

---

Still having issues? Join our Discord server for personalized support!