discord-jukebox-bot/TROUBLESHOOTING.md

Discord Jukebox Bot - Troubleshooting Guide

This guide helps you resolve common issues with the Discord Jukebox Bot.

Note: For more detailed diagnostics, run the bot in debug mode: ./jukebox-bot -debug or make run-debug

Important: The bot now streams real audio to Discord voice channels!

Common Errors

"Invalid Form Body" / "Value is not snowflake"

Error Message

Error starting bot: error creating command 'jukebox': HTTP 400 Bad Request, 
{"message": "Invalid Form Body", "code": 50035, "errors": {"guild_id": {"_errors": 
[{"code": "NUMBER_TYPE_COERCE", "message": "Value \"guild_id=1234567890123456\" is not snowflake."}]}}}

Cause

This happens when your Guild ID contains extra text or isn't in the correct format. Discord expects Guild IDs to be numeric snowflakes (just numbers).

Solution

1. Check your .env file for the JUKEBOX_DISCORD_GUILD_ID variable
2. Make sure it contains ONLY the numeric Guild ID, for example:

   JUKEBOX_DISCORD_GUILD_ID=1234567890123456789
   

3. Remove any extra text, spaces, quotes, or the variable name itself from the value
4. If you copied the line with JUKEBOX_DISCORD_GUILD_ID=, make sure you didn't accidentally include the line twice

Environment Variables Not Loading

Symptoms

• Bot reports "configuration is required" or "X is required" at startup
• Commands don't work properly
• Bot cannot connect to Discord or your Subsonic server

Solutions

1. Check your .env file location

   • Make sure the .env file is in the same directory as the bot executable
   • Run make debug to check if the .env file is detected

2. Check .env file format

   • Ensure each variable is on its own line
   • No spaces around the equal sign: JUKEBOX_DISCORD_TOKEN=yourtoken (correct)
   • Not: JUKEBOX_DISCORD_TOKEN = yourtoken (incorrect)
   • All variables must have the JUKEBOX_ prefix

3. Check variable names

   • Copy exact variable names from the .env.example file
   • Common issues: typos, missing prefix, wrong capitalization

4. Use direct environment variables

   • If .env isn't working, set variables directly in your shell:

     export JUKEBOX_DISCORD_TOKEN=yourtoken
     export JUKEBOX_SUBSONIC_SERVER=https://yourserver.com
     # etc...
     

Discord Connection Issues

Symptoms

• "Error creating Discord session" message
• "Error opening connection" message
• Bot starts but doesn't appear online in Discord

Solutions

1. Check your Discord bot token

   • Verify the token in the Discord Developer Portal
   • Generate a new token if necessary
   • Make sure you're using the bot token, not the client secret

2. Check bot permissions

   • The bot needs proper OAuth2 scopes and permissions
   • Required scopes: bot, applications.commands
   • Required permissions: Connect, Speak, Send Messages, Use Slash Commands

3. Verify slash commands

   • Commands may take up to an hour to register globally
   • Try using guild-specific commands for faster testing
   • Check if you provided the correct Guild ID

Subsonic Connection Issues

Symptoms

• "subsonic server is required" error
• "Error getting random songs" message
• Bot connects to Discord but doesn't play music

Solutions

1. Check your Subsonic credentials

   • Verify the server URL, username, and password
   • Try logging in through a web browser to confirm credentials
   • Server URL should include http:// or https:// prefix

2. Check Subsonic API compatibility

   • Ensure your server supports the Subsonic API
   • Try setting an older API version (e.g., JUKEBOX_SUBSONIC_VERSION=1.13.0)
   • Some Subsonic-compatible servers only implement part of the API

3. Network connectivity

   • Ensure the server is reachable from where the bot is running
   • Check firewall settings that might block connectivity
   • Try accessing the server from the same machine using a browser

Guild ID Issues

Symptoms

• "Invalid Form Body" error when starting the bot
• "Value is not snowflake" error message
• Bot starts but commands don't register

Solutions

1. Correct Guild ID Format

   • Guild ID should be only numbers with no other characters
   • Correct: JUKEBOX_DISCORD_GUILD_ID=123456789012345678
   • Incorrect: JUKEBOX_DISCORD_GUILD_ID=guild_id=123456789012345678
   • Incorrect: JUKEBOX_DISCORD_GUILD_ID="123456789012345678"

2. Check for Duplicates

   • Make sure the Guild ID variable isn't defined twice in your .env file
   • Sometimes copy-pasting causes duplicated variables

3. Get a Fresh Guild ID

   • Enable Developer Mode in Discord (Settings > Advanced)
   • Right-click your server and select "Copy ID"
   • Use this exact ID in your configuration

Voice Connection Issues

Symptoms

• Bot responds to commands but doesn't join voice channel
• "Error joining voice channel" message
• Bot joins voice channel but doesn't play audio

Solutions

1. Check Discord permissions

   • Bot needs "Connect" and "Speak" permissions in the voice channel
   • Try giving the bot Administrator permission temporarily to test

2. User in voice channel

   • The user must be in a voice channel when using /jukebox play
   • The bot will join the user's current channel

3. Guild ID configuration

   • Make sure your JUKEBOX_DISCORD_GUILD_ID is correct
   • You can get the Guild ID by enabling Developer Mode in Discord, then right-clicking the server and selecting "Copy ID"

Audio Playback Issues

Symptoms

• Bot joins voice channel successfully but no sound plays
• "Error creating encoding session" message in logs
• Songs appear to be playing (bot shows "Now playing") but no audio

Solutions

1. Check Subsonic streaming capabilities

   • Verify your Subsonic server allows streaming
   • Test streaming directly in your browser by visiting the stream URL (visible in debug logs)
   • Some Subsonic servers require additional authentication for streaming

2. Check audio format compatibility

   • The bot now converts audio to Opus format required by Discord
   • Some audio formats might not be compatible with the encoder
   • If specific songs don't play, try different ones to rule out format issues

3. Network issues

   • Ensure your Subsonic server is accessible from where the bot is running
   • Check firewall settings that might be blocking the audio stream
   • Audio streaming requires stable, low-latency connectivity

4. Discord limitations

   • Discord has bandwidth limits that might affect audio quality
   • Try a different voice region if audio is choppy or not playing
   • The default bitrate (96kbps) should work on most Discord servers

Debugging

For better debugging information:

1. Run the bot in debug mode

   ./jukebox-bot -debug
   

   or

   make run-debug
   

2. Use the debug command for environment checks

   make debug
   

3. Check log output

   • Look for error messages in the console
   • The debug mode shows detailed API requests and responses
   • Audio playback simulation will show progress updates

4. Try running directly

   • Run the bot directly with Go:

   cd discord-jukebox-bot
   go run ./cmd/bot -debug
   

5. Audio debugging

   • In debug mode, the bot will print the exact stream URL being used
   • Copy this URL and try opening it in a browser to test if streaming works
   • Look for "Audio streaming in progress" messages showing actual bytes sent
   • If you see "error creating encoding session", the audio format may be incompatible

Still Having Issues?

If you're still experiencing problems:

1. Open an issue on the GitHub repository with:

   • The exact error message
   • Your environment (OS, Go version)
   • Steps to reproduce the issue
   • Output from make debug

2. Make sure to remove any sensitive information (tokens, passwords) before sharing logs.