Troubleshooting rustycord¶

Common issues and solutions when using rustycord.

Bot Not Responding to Commands¶

Symptoms¶

Bot connects successfully
Bot appears online in Discord
Commands like !ping or !help don't trigger any response
No message events in logs

Solution: Enable Message Content Intent¶

This is the most common issue. Discord requires explicit permission to read message content.

Go to Discord Developer Portal:
Visit https://discord.com/developers/applications
Select your application
Navigate to Bot section:
Click "Bot" in the left sidebar
Enable Message Content Intent:
Scroll down to "Privileged Gateway Intents"
Toggle ON "Message Content Intent"
Save changes

Update your code to use proper intents:

use rustycord::gateway::intents;

// Include message-related intents
let intents = intents::GUILDS | intents::GUILD_MESSAGES | intents::MESSAGE_CONTENT;
let mut bot = BotBase::new(Some(intents)).await;

Verify in Logs¶

Look for these log messages when your bot starts:

✅ Message handler registered: YourHandler (Total: 1)
🚀 Bot is ready!
🏰 Joined guild: YourServerName

Authentication Issues¶

Invalid Token Error¶

Error: HTTP error: 401 Unauthorized

Solutions: 1. Check your .env file:

DISCORD_TOKEN=your_actual_bot_token_here

2. No extra spaces or quotes around the token 3. Regenerate token if necessary in Discord Developer Portal

Token Not Found Error¶

DISCORD_TOKEN environment variable not set

Solutions: 1. Create .env file in your project root 2. Copy from example: cp .env.example .env 3. Add dotenv dependency in Cargo.toml:

[dependencies]
dotenv = "0.15"

4. Call dotenv in code:

dotenv::dotenv().ok();

Permission Issues¶

Missing Access Error¶

Error: Missing Access

Solutions: 1. Re-invite your bot with proper permissions 2. Check bot role position (should be above roles it needs to manage) 3. Grant essential permissions: - Send Messages - Read Message History - Read Messages

Generate proper invite URL:¶

Discord Developer Portal → Your App → OAuth2 → URL Generator
Select Scopes: bot
Select Permissions:
Send Messages
Read Message History
Use Slash Commands (if needed)
Use generated URL to invite bot

Connection Issues¶

WebSocket Connection Failed¶

Error: Connection timeout
Error: WebSocket connection failed

Solutions: 1. Check internet connection 2. Verify Discord status: https://discordstatus.com 3. Check firewall settings 4. Try different network (mobile hotspot to test)

Gateway Connection Issues¶

Failed to connect to Discord gateway

Solutions: 1. Check bot token validity 2. Verify intents configuration 3. Check rate limits (too many connection attempts)

Message Handler Issues¶

Handler Not Triggered¶

Handler registered but not executing

Check these: 1. Message Content Intent enabled 2. Bot not responding to its own messages:

if message.author.bot.unwrap_or(false) {
    return Ok(());
}

3. Correct message format (right prefix, etc.)

Multiple Responses¶

Bot responding multiple times to same command

Solutions: 1. Remove duplicate handlers 2. Check for multiple bot instances 3. Ensure handlers return early when appropriate

Logging and Debugging¶

Enable Debug Logging¶

// In your main function
logger::setup_logger("debug".to_string())?;

// Or via environment variable
RUST_LOG=debug cargo run

Check Log Files¶

Most examples create output.log:

tail -f output.log
grep -i "error" output.log
grep -i "message" output.log

Common Log Messages¶

Success indicators:

✅ Successfully authenticated as: YourBot
🔌 Connected to The Discord
🚀 Bot is ready!
🏰 Joined guild: YourServer

Problem indicators:

❌ Authentication failed
❌ Failed to connect to Discord gateway
Error: 401 Unauthorized
Error: Missing Access

Performance Issues¶

High CPU Usage¶

Bot using too much CPU

Solutions: 1. Check for infinite loops in message handlers 2. Avoid blocking operations in async handlers 3. Use appropriate log levels (avoid "trace" in production)

Memory Leaks¶

Memory usage keeps growing

Solutions: 1. Check for unbounded collections in handlers 2. Properly drop resources in async code 3. Use weak references where appropriate

Development Tips¶

Quick Testing¶

Create a test server for development
Use debug logging during development
Test with simple commands first (!ping)

Code Organization¶

// Separate concerns
struct MyBot {
    client: Client,
    commands: PrefixListener,
}

impl MyBot {
    async fn setup(&mut self) -> Result<(), Box<dyn Error>> {
        // Setup logic here
    }
}

Error Handling¶

// Always handle errors gracefully
match some_operation().await {
    Ok(result) => {
        log::info!("Operation successful: {:?}", result);
    }
    Err(e) => {
        log::error!("Operation failed: {}", e);
        // Don't panic, return gracefully
        return Err(e);
    }
}

Getting Help¶

If you're still having issues:

Check the examples in the repository
Review the documentation
Search existing issues on GitHub
Create a minimal reproduction case
Include logs and error messages when asking for help

Useful Information to Include¶

When reporting issues: - Rust version: rustc --version - Operating system - Complete error messages - Minimal code that reproduces the issue - Bot permissions and intents configuration