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.