Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/onesoft-sudo/sudobot/llms.txt

Use this file to discover all available pages before exploring further.

This page covers the most common issues encountered when deploying SudoBot, along with their causes and fixes.

​
The bot doesn’t come online

Symptoms: The process starts but the bot never appears online in Discord. Checklist:
  • Confirm TOKEN in your .env is the correct bot token from the Discord Developer Portal
  • Confirm the bot has been invited to your server with the correct permissions
  • Check the logs for authentication errors: pm2 logs sudobot or docker compose logs sudobot

​
Database connection errors

Symptoms: Startup fails with ECONNREFUSED, connection refused, or password authentication failed. Fixes: 
# Test the connection manually
psql "$DB_URL" -c "SELECT 1;"
  • Make sure DB_URL uses the correct host, port, user, password, and database name
  • If using Docker Compose, the database host should be postgres (the service name), not localhost
  • If using Kubernetes, the host is injected automatically via POSTGRES_SERVICE_SERVICE_HOST
  • Verify PostgreSQL is running and accepting connections on the expected port

​
Slash commands don’t appear

Symptoms: The bot is online but /commands don’t show up in Discord. Fix: Register the commands with Discord’s API: 
# Register commands (development guild if HOME_GUILD_ID is set and NODE_ENV=development)
./blazew run -- -u

# Force global registration
./blazew run -- -u -g
Global command registration can take up to an hour to propagate across Discord. Guild-specific commands appear instantly.

​
Heap out of memory during build

Symptoms: ./blazew build fails with a JavaScript heap allocation error. Fix: Increase Node.js heap size: 
NODE_OPTIONS=--max-old-space-size=4096 ./blazew build
Alternatively, download a prebuilt release from GitHub Releases instead of building from source.

​
Missing or broken emojis in bot messages

Symptoms: Bot messages contain empty spaces or ? where emojis should be. Fix: Download and upload the custom emojis to your Home Guild:
  1. Download emojis from onesoftnet.eu.org/downloads/sudo/emojis
  2. Upload them to the guild specified in HOME_GUILD_ID
  3. Make sure the bot has access to that guild

​
Extensions not loading

Symptoms: Custom extension commands don’t appear after restart. Checklist:
  • Confirm EXTENSIONS_DIRECTORY is set in .env and points to the correct path
  • Confirm the extension directory contains a valid extension.json
  • Confirm the extension was built (npm run build inside the extension directory)
  • Check logs for extension-specific errors on startup

​
Config changes not taking effect

Symptoms: You edited config.json or system.json but the bot behaviour hasn’t changed. Fix: SudoBot reads config files from SUDO_PREFIX/config/, not the repository’s config/ directory. Make sure you copied your edited files to the correct location and restart the bot. 
cp config/config.json $SUDO_PREFIX/config/config.json
cp config/system.json $SUDO_PREFIX/config/system.json
pm2 restart sudobot

​
Getting more help

If the issue isn’t covered here:

Build docs developers (and LLMs) love

Get started for freeTalk to us