Skip to content

Troubleshooting

Jump to bottom
c0bra edited this page Jul 24, 2026 · 1 revision

Troubleshooting

Bot container does not start

  • Check the bot logs: docker compose logs -f bot or podman compose logs -f bot.
  • Confirm .env exists at the repository root after running utils/init.sh.
  • Confirm required values from utils/.env.example are filled, especially DISCORD_TOKEN, SUPABASE_API_KEY, POSTGRES_PASSWORD, and DATABASE_URL.
  • Confirm the database service is healthy; the bot waits for the PostgreSQL healthcheck.

Do not paste real .env values, tokens, or credentials into chat or issue trackers.

Database service is unhealthy

  • Check database logs with docker compose logs -f db or podman compose logs -f db.
  • Ensure POSTGRES_PASSWORD is set; Compose requires it.
  • The database binds to 127.0.0.1:5432 for local host access only. Bot-to-database traffic uses the internal Compose network and db:5432.
  • If using an existing volume, verify required migrations were applied in order.

Slash command returns Command failed. Check bot.log.

Check app/logs/ or container logs for the exception. Common causes are missing Discord permissions, unavailable Battlevive/Supabase API credentials, or database connectivity problems.

/rank says You are not registered.

The bot could not find a synced user row linked to your Discord ID. Confirm the Battlevive account exists, its Discord username can be matched to the Discord member, and ask an admin to run /refresh.

Leaderboard channel cannot be configured

/config leaderboard channel only accepts text or announcement/news channels. The bot must have View Channel, Send Messages, Attach Files, and Read Message History in the selected channel.

Leaderboard limit rejected

/config leaderboard limit accepts values from 1 through 50. Omit the amount to use the maximum of 50.

Roles are not assigned

  • Run /create_roles to create the rank roles and Battlevive Player role.
  • Ensure the bot has Manage Roles and its highest role is above the roles it needs to manage.
  • Run /refresh after roles and permissions are fixed.
  • Check logs for member matching failures or Discord permission errors.

Existing database volume missing schema changes

Container initialization SQL is only automatic for fresh PostgreSQL volumes. Apply missing idempotent migration files manually and in numeric order, for example:

psql "$DATABASE_URL" -f app/init-db/04_guild_config.sql
psql "$DATABASE_URL" -f app/init-db/05_leaderboards.sql
psql "$DATABASE_URL" -f app/init-db/06_leaderboard_disk_cache.sql

Debug dump commands

/debug_get_db_data and /debug_get_battlevive_data write and return JSON dumps of users, lobbies, and ratings. Use them only for controlled diagnostics. The output can contain synced user and match data; do not share it publicly.

Clone this wiki locally