Troubleshooting

Common issues and their solutions.

Bot Won't Start

Check Node.js Version

node -v

Must be 16.x or higher. Recommended: 18.x or 20.x LTS.

Verify config.yml Syntax

node -e "const y = require('js-yaml'); const fs = require('fs'); y.load(fs.readFileSync('config.yml', 'utf8')); console.log('Valid YAML')"

A malformed YAML file will throw a parse error. Check for:

• Incorrect indentation (YAML uses spaces, not tabs)
• Missing quotes around strings with special characters
• Invalid ${VAR} references without corresponding .env entries

Reinstall Dependencies

rm -rf node_modules
npm install

Rebuild After Changes

npm run build

If you edited TypeScript source files, you must rebuild before starting.

No Music Playback

Is Lavalink Running?

curl http://localhost:2333/version

If this fails, Lavalink is not accessible. Start it:

java -jar Lavalink.jar

Do Credentials Match?

The auth in config.yml must exactly match the password in Lavalink's application.yml:

# config.yml
lavalink:
  NODES:
    - auth: "youshallnotpass"
 
# application.yml
lavalink:
  server:
    password: "youshallnotpass"

Is the Bot in a Voice Channel?

The bot needs Connect and Speak permissions in the target voice channel.

YouTube Not Working?

YouTube may require the youtube-source plugin (opens in a new tab) with valid poToken configuration in Lavalink's application.yml. Check the plugin documentation for current requirements.

Database Connection Fails

Is the Database Server Running?

# MongoDB
mongosh --eval "db.runCommand({ ping: 1 })"
 
# MySQL
mysql -u root -p -e "SELECT 1"
 
# PostgreSQL
psql -U postgres -c "SELECT 1"

Check Credentials

Verify the host, port, user, password, and database values in config.yml match your database server.

Check Firewall

Ensure the database port is accessible from the bot server. Common ports:

• MongoDB: 27017
• MySQL: 3306
• PostgreSQL: 5432

Dashboard Not Loading

Is the REST API Running?

Check the bot logs for:

Server running at port 2555

If missing, verify features.RestAPI.enable is true in config.

Is the Frontend Running?

cd frontend
npm run dev

CORS Issues

Ensure DashboardUrl / FRONTEND_URL exactly matches the frontend URL (including protocol and port):

• Development: http://localhost:3000 or http://localhost:5173
• Production: https://yourdomain.com

OAuth2 Not Working

Verify all four values match:

1. DiscordClientId matches your application's Client ID in the Discord Developer Portal.
2. DiscordClientSecret matches your application's Client Secret.
3. DiscordRedirectUri matches a redirect URI registered in Discord Developer Portal → OAuth2 → Redirects.
4. The redirect URI protocol matches (http vs https).

Session Cookie Not Persisting

For production (cross-domain):

• Set NODE_ENV=production in .env
• Ensure the API is behind HTTPS (required for Secure cookies)
• Ensure SameSite=None is working (requires HTTPS on both API and frontend)

Slash Commands Not Appearing

1. Commands deploy automatically on bot start via DeployService.
2. Global commands may take up to 1 hour for Discord's cache to update.
3. To force-remove all commands:

   node scripts/clearSlash.js
   Then restart the bot.

Sharding Issues

Small Bots (< 2,500 guilds)

Use single shard:

bot:
  SHARDING_SYSTEM:
    shardsPerClusters: 1
    totalClusters: 1

Start with:

npm start

Large Bots (> 2,500 guilds)

Increase clusters:

bot:
  SHARDING_SYSTEM:
    shardsPerClusters: 2
    totalClusters: 4

Start with:

npm run start:shards

Premium / Patreon / Ko-fi Issues

Patreon

1. Ensure Patreon.Enable is true.
2. Verify the AccessToken is a valid Creator Access Token.
3. Verify the CampaignId is correct (use node scripts/getCampignId.js).
4. Check that the webhook URL points to your WebServer.

Ko-fi

1. Ensure KoFi.Enable is true.
2. Verify the VerificationToken matches your Ko-fi webhook settings.
3. Webhook URL format: https://your-webserver-domain/kofi

Premium Not Showing on Dashboard

1. Check the user's premium status via the API: GET /api/user/premium
2. Verify DASHBOARD_ACCESS config is set correctly.
3. Premium role: ensure PremiumRole.GuildId and PremiumRole.RoleId are correct.

AI Chat Not Working

Music Trivia Issues

Log Files

Logs are written to the logs/ directory with daily rotation via Winston.

# View latest log (PowerShell)
Get-Content logs/*.log -Tail 100
 
# View latest log (Linux/Mac)
tail -100 logs/*.log

Enable debug mode for verbose output:

bot:
  DEBUG_MODE: true

Common Error Messages