Common Setup Issues
Bot Won’t Start
Error: Invalid Token
Error: Invalid Token
Problem: Bot fails to login with “Invalid Token” error.Symptoms:Solution:
Regenerate Token
If the token is old or compromised:
- Go to Discord Developer Portal
- Select your application
- Go to “Bot” section
- Click “Reset Token”
- Copy the new token to your
.envfile
Error: Cannot Find Module
Error: Cannot Find Module
Problem: Missing dependencies when starting the bot.Symptoms:Solution:
Bot Connects But Doesn't Respond
Bot Connects But Doesn't Respond
Problem: Bot comes online but doesn’t react to commands or messages.Causes:
- Missing required intents
- Insufficient permissions
- Commands not registered
Enable Privileged Intents
In Discord Developer Portal:
- Go to your application
- Navigate to “Bot” section
- Enable “Message Content Intent”
- Enable “Server Members Intent”
- Save changes and restart bot
Database Errors
SQLite Connection Issues
Error: ENOENT - No Such File or Directory
Error: ENOENT - No Such File or Directory
Error: Database is Locked
Error: Database is Locked
Problem: SQLite database is locked by another process.Symptoms:Solutions:
- Close Existing Connections:
- Check for Multiple Bot Instances:
- Remove Lock Files (last resort):
Database Corruption
Database Corruption
Problem: Database file is corrupted and cannot be opened.Symptoms:Recovery Steps:
- Backup Current Database:
- Try SQLite Recovery:
- Rebuild Database (if recovery fails):
You’ll need to reconfigure server settings and re-add phrases after rebuilding.
Command Issues
Slash Commands Not Appearing
Commands Don't Show in Discord
Commands Don't Show in Discord
Problem: Slash commands aren’t visible when typing
/.Solutions:Check Command Registration
Look for this message in console on startup:If not present, commands failed to register.
Verify Bot Permissions
When inviting the bot, ensure you include:
applications.commandsscopebotscope
Force Command Refresh
Commands can take up to 1 hour to update globally. To refresh immediately:
- Kick the bot from your server
- Reinvite with correct permissions
- Wait 5 minutes
- Check for commands
Command Responses Timeout
Interaction Failed Error
Interaction Failed Error
Problem: Commands timeout with “This interaction failed” message.Causes:
- Command takes longer than 3 seconds to respond
- Command code has errors
- Database queries are slow
Bot Reply Issues
Bot Doesn’t Reply to Messages
Check Reply Channel Configuration
Check Reply Channel Configuration
Problem: Bot is in server but not replying to any messages.Diagnosis:Solution:
Use the Or add directly to database:
/settings command to add reply channels:Check for Opt-Out Users
Check for Opt-Out Users
Problem: Bot doesn’t reply to specific users.Check opt-out list:Remove user from opt-out:
Reply Cooldown Active
Reply Cooldown Active
No Phrases Configured
No Phrases Configured
Problem: Channel is configured but bot has nothing to say.Check phrases:Add phrases:
Permission Errors
Missing Permissions
Error: Missing Permissions
Problem: Bot can’t perform actions due to missing permissions.Common Errors:Required Permissions:
How to Fix:
| Feature | Required Permission |
|---|---|
| Read messages | ViewChannel |
| Send replies | SendMessages |
| Add reactions | AddReactions |
| Embed links | EmbedLinks |
| Attach files | AttachFiles |
| Manage messages | ManageMessages (optional) |
| Kick members | KickMembers (if needed) |
- Go to Server Settings → Roles
- Find bot’s role
- Enable required permissions
- Check channel-specific overrides
- Ensure bot role is above target roles in hierarchy
Channel Access Issues
Logging & Debugging
Enable Debug Logging
Log File Locations
Performance Issues
High Memory Usage
Memory Leak Detection
Memory Leak Detection
Check memory usage:Common causes:
- Not closing database connections
- Event listener accumulation
- Large cache size
Slow Response Times
Optimize Database Queries
Optimize Database Queries
Problem: Commands take too long to respond.Solutions:
- Add indexes:
- Use prepared statements:
- Cache frequently accessed data:
Getting Help
GitHub Issues
Report bugs or request features on GitHub
Discord Server
Join the support server for live help
Check Logs
Always check
data/logs.db before asking for helpProvide Details
Include error messages, logs, and steps to reproduce
Useful Commands for Debugging
Most issues can be resolved by checking the console output and database logs. Always check these first before seeking help.