Skip to main content

Common Setup Issues

Bot Won’t Start

Problem: Bot fails to login with “Invalid Token” error.Symptoms:
Error: An invalid token was provided.
    at WebSocketManager.connect
Solution:
1

Verify Token in .env

Check that your .env file contains the correct bot token:
TOKEN=your_bot_token_here
2

Regenerate Token

If the token is old or compromised:
  1. Go to Discord Developer Portal
  2. Select your application
  3. Go to “Bot” section
  4. Click “Reset Token”
  5. Copy the new token to your .env file
3

Check for Extra Spaces

Ensure there are no spaces or quotes around the token:
# Correct
TOKEN=MTIzNDU2Nzg5MDEyMzQ1Njc4.GhI_Jk.LmNoPqRsTuVwXyZ123456789

# Incorrect
TOKEN="MTIzNDU2..." # No quotes
TOKEN= MTIzNDU2... # No space after =
Problem: Missing dependencies when starting the bot.Symptoms:
Error: Cannot find module 'discord.js'
Solution:
# Install all dependencies
npm install

# Or if using yarn
yarn install

# For specific missing modules
npm install discord.js sqlite3 dotenv colors
Always run npm install after cloning the repository or pulling updates.
Problem: Bot comes online but doesn’t react to commands or messages.Causes:
  1. Missing required intents
  2. Insufficient permissions
  3. Commands not registered
Solution:
1

Verify Intents

Check src/intents.js includes required intents:
const INTENTS = [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent, // Required!
    GatewayIntentBits.GuildMembers,
];
2

Enable Privileged Intents

In Discord Developer Portal:
  1. Go to your application
  2. Navigate to “Bot” section
  3. Enable “Message Content Intent”
  4. Enable “Server Members Intent”
  5. Save changes and restart bot
3

Check Bot Permissions

Ensure bot has these permissions in your server:
  • Read Messages/View Channels
  • Send Messages
  • Send Messages in Threads
  • Embed Links
  • Attach Files
  • Read Message History
  • Add Reactions

Database Errors

SQLite Connection Issues

Problem: Bot can’t create or access database files.Symptoms:
Error: ENOENT: no such file or directory, open '/path/to/data/serverId.db'
Solution:
1

Create Data Directory

mkdir -p data
chmod 755 data
2

Check Write Permissions

# Check current permissions
ls -la

# Fix if needed
chmod -R 755 .
3

Verify Path in Code

Ensure database paths use path.join() correctly:
const dbPath = path.join(__dirname, '..', 'data', 'database.db');
Problem: SQLite database is locked by another process.Symptoms:
Error: SQLITE_BUSY: database is locked
Solutions:
  1. Close Existing Connections:
// Always close databases
try {
    // Database operations
} finally {
    db.close();
}
  1. Check for Multiple Bot Instances:
# Find running node processes
ps aux | grep node

# Kill if needed
pkill -f "node src/client.js"
  1. Remove Lock Files (last resort):
# Stop bot first
rm data/*.db-journal
rm data/*.db-wal
Only remove lock files when the bot is completely stopped to avoid data corruption.
Problem: Database file is corrupted and cannot be opened.Symptoms:
Error: file is not a database
Error: database disk image is malformed
Recovery Steps:
  1. Backup Current Database:
cp data/serverId.db data/serverId.db.backup
  1. Try SQLite Recovery:
sqlite3 data/serverId.db ".recover" | sqlite3 data/serverId_recovered.db
  1. Rebuild Database (if recovery fails):
# Remove corrupted database
rm data/serverId.db

# Bot will create new database on next start
npm start
You’ll need to reconfigure server settings and re-add phrases after rebuilding.

Command Issues

Slash Commands Not Appearing

Problem: Slash commands aren’t visible when typing /.Solutions:
1

Check Command Registration

Look for this message in console on startup:
Successfully registered application commands. Total commands: 5
If not present, commands failed to register.
2

Verify Bot Permissions

When inviting the bot, ensure you include:
  • applications.commands scope
  • bot scope
Reinvite URL format:
https://discord.com/api/oauth2/authorize?client_id=YOUR_BOT_ID&permissions=274878221376&scope=bot%20applications.commands
3

Force Command Refresh

Commands can take up to 1 hour to update globally. To refresh immediately:
  1. Kick the bot from your server
  2. Reinvite with correct permissions
  3. Wait 5 minutes
  4. Check for commands
4

Check Registration Errors

Enable debug logging in utils/registerCommands.js:
try {
    const registeredCommands = await rest.put(
        Routes.applicationCommands(client.user.id),
        { body: commands }
    );
    console.log('Registered:', registeredCommands);
} catch (error) {
    console.error('Registration failed:', error);
}

Command Responses Timeout

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
Solution:
module.exports = {
    data: new SlashCommandBuilder()
        .setName('slowcommand')
        .setDescription('A slow command'),
    async execute(interaction) {
        // Defer immediately for long operations
        await interaction.deferReply();
        
        try {
            // Long operation here
            const result = await longDatabaseQuery();
            
            // Edit the deferred reply
            await interaction.editReply({
                content: 'Operation complete!'
            });
        } catch (error) {
            await interaction.editReply({
                content: 'Error: ' + error.message
            });
        }
    }
};
Always use deferReply() for operations that might take more than 2 seconds.

Bot Reply Issues

Bot Doesn’t Reply to Messages

Problem: Bot is in server but not replying to any messages.Diagnosis:
# Check console for message logs
# You should see:
0% - ServerName - #channel - username - message

# If you see 0%, the channel is not configured
Solution: Use the /settings command to add reply channels:
/settings action:add-channel channel:#general
Or add directly to database:
INSERT INTO replyChannels (id, chance) VALUES ('channel_id', 6);
Problem: Bot doesn’t reply to specific users.Check opt-out list:
SELECT * FROM OptOutList;
Remove user from opt-out:
DELETE FROM OptOutList WHERE userTag = 'Username#1234';
Problem: Bot replied once but won’t reply again.Explanation: Cooldown system prevents spam.Check cooldown:
SELECT * FROM cooldowns WHERE serverId = 'server_id' AND channelId = 'channel_id';
Clear cooldown (for testing):
DELETE FROM cooldowns WHERE serverId = 'server_id';
Problem: Channel is configured but bot has nothing to say.Check phrases:
SELECT * FROM phrases;
Add phrases:
INSERT INTO phrases (phrase) VALUES ('Hello!');
INSERT INTO phrases (phrase) VALUES ('Hi there!');
INSERT INTO phrases (phrase) VALUES ('Hey!');

Permission Errors

Missing Permissions

Error: Missing Permissions

Problem: Bot can’t perform actions due to missing permissions.Common Errors:
DiscordAPIError: Missing Permissions
DiscordAPIError: Missing Access
Required Permissions:
FeatureRequired Permission
Read messagesViewChannel
Send repliesSendMessages
Add reactionsAddReactions
Embed linksEmbedLinks
Attach filesAttachFiles
Manage messagesManageMessages (optional)
Kick membersKickMembers (if needed)
How to Fix:
  1. Go to Server Settings → Roles
  2. Find bot’s role
  3. Enable required permissions
  4. Check channel-specific overrides
  5. Ensure bot role is above target roles in hierarchy

Channel Access Issues

// Check if bot can see channel
if (!channel.permissionsFor(client.user).has('ViewChannel')) {
    console.log('Bot cannot see this channel');
}

// Check if bot can send messages
if (!channel.permissionsFor(client.user).has('SendMessages')) {
    console.log('Bot cannot send messages here');
}

Logging & Debugging

Enable Debug Logging

1

Check Console Output

All events are logged to console with timestamps and color coding:
12:34:56    ServerName - #channel - username - message
12:34:57    ServerName - #channel - username - /command
2

Check Database Logs

Open the logs database:
sqlite3 data/logs.db
Query today’s logs:
SELECT * FROM "03-04-2026" ORDER BY time DESC LIMIT 50;
3

Add Debug Logging

Add temporary debug logs in your code:
const { Debug } = require('./utils/logging');

Debug('Variable value: ' + JSON.stringify(variable));

Log File Locations

project/
├── data/
│   ├── logs.db              # All console logs
│   ├── serverId.db          # Server settings
│   ├── leaderboards.db      # User statistics
│   ├── optoutlist.db        # Opted-out users
│   └── replyCooldowns.db    # Reply cooldowns

Performance Issues

High Memory Usage

Check memory usage:
const used = process.memoryUsage();
console.log(`Memory: ${Math.round(used.heapUsed / 1024 / 1024)} MB`);
Common causes:
  1. Not closing database connections
  2. Event listener accumulation
  3. Large cache size
Solutions:
// Always close databases
db.close();

// Remove listeners when done
client.removeListener('messageCreate', listener);

// Clear caches periodically
client.sweepMessages();

Slow Response Times

Problem: Commands take too long to respond.Solutions:
  1. Add indexes:
CREATE INDEX idx_userid ON current(userID);
CREATE INDEX idx_channelid ON replyChannels(id);
  1. Use prepared statements:
const stmt = db.prepare('SELECT * FROM phrases WHERE id = ?');
stmt.get([id], callback);
stmt.finalize();
  1. Cache frequently accessed data:
const cache = new Map();

if (cache.has(serverId)) {
    return cache.get(serverId);
}

const settings = await getSettings(serverId);
cache.set(serverId, settings);

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 help

Provide Details

Include error messages, logs, and steps to reproduce

Useful Commands for Debugging

# Check if bot process is running
ps aux | grep node

# Monitor logs in real-time
tail -f npm-debug.log

# Check database integrity
sqlite3 data/database.db "PRAGMA integrity_check;"

# List all tables in database
sqlite3 data/database.db ".tables"

# Export database to SQL
sqlite3 data/database.db ".dump" > backup.sql

# Test bot token validity
curl -H "Authorization: Bot YOUR_TOKEN_HERE" \
     https://discord.com/api/v10/users/@me
Most issues can be resolved by checking the console output and database logs. Always check these first before seeking help.

Quick Fixes Checklist

1

Restart the Bot

Many issues resolve with a simple restart
# Stop
Ctrl+C

# Start
npm start
2

Update Dependencies

Ensure all packages are up to date
npm update
3

Check Environment Variables

Verify .env file has all required values
cat .env
4

Clear Node Cache

Remove cached modules and reinstall
rm -rf node_modules package-lock.json
npm install
5

Verify Bot Token

Test token is valid and has required scopes
If you encounter persistent issues, check the GitHub repository for known issues and recent updates that might affect your installation.

Build docs developers (and LLMs) love