Troubleshooting

Common issues and solutions when working with Salada

Connection Issues

Node Connection Failed

Check if your Lavalink server is running and accessible.

node = bot.salad.nodes[0]
if not node.connected:
    print('Node is not connected')
    print(f'Session ID: {node.sessionId}')

Solutions:

• Verify Lavalink server is running: java -jar Lavalink.jar
• Check if the port is correct in your configuration
• Ensure firewall isn’t blocking the connection
• Verify the password matches in both application.yml and your bot config

Voice Channel Issues

Ensure your bot has proper permissions to join voice channels.

import discord

voice_channel = interaction.user.voice.channel
permissions = voice_channel.permissions_for(interaction.guild.me)

if not permissions.connect or not permissions.speak:
    raise Exception('Missing voice channel permissions')

Solutions:

• Grant “Connect” and “Speak” permissions to your bot
• Check if the voice channel has user limits
• Verify the user is in a voice channel before creating connection
• Ensure the bot isn’t already in another voice channel

Authentication Failed

If you’re getting authentication errors with Lavalink:

NODE_CONFIG = {
    'host': 'localhost',
    'port': 2333,
    'auth': 'youshallnotpass',
    'ssl': False
}

Solutions:

• Double-check the password in your application.yml file
• Restart the Lavalink server after changing configuration
• Ensure you’re using the correct host and port

Common Errors

Error: No available nodes

Cause: Lavalink node is disconnected

Solution:

• Check node configuration and ensure Lavalink server is running
• Verify network connectivity between bot and Lavalink server
• Check Lavalink server logs for connection errors
• Restart both Lavalink server and your bot

node = bot.salad.nodes[0]
if not node.connected or not node.sessionId:
    print('Node is not ready')
    print(f'Connected: {node.connected}')
    print(f'Session ID: {node.sessionId}')

Error: Track load failed

Cause: Track couldn’t be loaded or played

Solution:

• Check if the track URL is valid and accessible
• Verify your Lavalink server has the required audio sources enabled
• Try searching with different platforms (YouTube, SoundCloud, etc.)
• Check your internet connection and DNS resolution

# Enable different sources in application.yml
sources:
  youtube: true
  bandcamp: true
  soundcloud: true
  twitch: true

Error: Player not found

Cause: Trying to control a non-existent player

Solution:

• Create a player connection first before controlling playback
• Check if the player was destroyed or disconnected
• Verify you’re using the correct guild ID

player = bot.salad.getPlayer(guild_id)
if not player:
    player = await bot.salad.createConnection({
        'guildId': guild_id,
        'textChannel': text_channel_id,
        'voiceChannel': voice_channel_id
    })
    await voice_channel.connect()

AttributeError: 'NoneType' object has no attribute 'voice'

Cause: User is not in a voice channel

Solution:

• Always check if the user is in a voice channel before creating connections

if not interaction.user.voice:
    await interaction.followup.send('❌ You need to be in a voice channel!')
    return

if not interaction.user.voice.channel:
    await interaction.followup.send('❌ You need to be in a voice channel!')
    return

Error: Missing Access

Cause: Bot doesn’t have permission to join the voice channel

Solution:

• Check bot permissions in the specific voice channel
• Ensure the voice channel isn’t full
• Verify the channel isn’t restricted to certain roles

voice_channel = interaction.user.voice.channel
bot_permissions = voice_channel.permissions_for(interaction.guild.me)

if not bot_permissions.connect or not bot_permissions.speak:
    await interaction.followup.send('❌ I need Connect and Speak permissions!')
    return

Error: Player destroyed

Cause: Attempting to use a destroyed player

Solution:

• Check if player is destroyed before using it
• Create a new player if the old one was destroyed

player = bot.salad.getPlayer(guild_id)
if not player or player.destroyed:
    player = await bot.salad.createConnection({
        'guildId': guild_id,
        'voiceChannel': voice_channel_id,
        'textChannel': text_channel_id
    })

Search Issues

No Search Results

If searches aren’t returning results:

result = await bot.salad.resolve('never gonna give you up', source='ytsearch', requester=user)

result = await bot.salad.resolve('lofi hip hop', source='scsearch', requester=user)

result = await bot.salad.resolve('classical music', source='ytmsearch', requester=user)

Solutions:

• Use correct source: ytsearch, ytmsearch, scsearch
• Check if the search sources are enabled in Lavalink
• Try simpler search terms
• Verify internet connectivity

Search Timeout

try:
    result = await bot.salad.resolve(query, requester=interaction.user)
    
    if not result.get('tracks'):
        await interaction.followup.send('❌ No tracks found!')
        return
        
except Exception as error:
    print(f'Search failed: {error}')
    await interaction.followup.send('❌ Search failed, please try again!')
    return

Handle Empty Results

result = await bot.salad.resolve(query, requester=interaction.user)

load_type = result.get('loadType')

if load_type == 'empty':
    await interaction.followup.send('❌ No results found!')
    return

if load_type == 'error':
    exception = result.get('exception', {})
    error_message = exception.get('message', 'Unknown error')
    await interaction.followup.send(f'❌ Error: {error_message}')
    return

Performance Issues

High Memory Usage

Monitor and limit concurrent connections:

MAX_PLAYERS = 50

if len(bot.salad.players) >= MAX_PLAYERS:
    await interaction.followup.send('❌ Too many active players, please try again later!')
    return

Audio Lag or Stuttering

Solutions:

• Increase buffer size in Lavalink configuration
• Use a dedicated server for Lavalink
• Check network bandwidth and latency
• Ensure your bot has enough CPU and memory resources

Import Errors

ModuleNotFoundError

ModuleNotFoundError: No module named 'salada'

Solution:

pip install salada

pip install --upgrade salada

Missing Dependencies

ModuleNotFoundError: No module named 'aiohttp'

Solution:

pip install aiohttp
pip install discord.py

Discord.py Issues

Intents Not Enabled

discord.errors.PrivilegedIntentsRequired: Shard ID None is requesting privileged intents

Solution:

import discord

INTENTS = discord.Intents.default()
INTENTS.message_content = True
INTENTS.voice_states = True
INTENTS.guilds = True

bot = commands.Bot(command_prefix='!', intents=INTENTS)

Enable intents in Discord Developer Portal:

1. Go to your application settings
2. Navigate to “Bot” section
3. Enable “Message Content Intent”
4. Enable “Server Members Intent” if needed

Voice Connection Issues

await interaction.user.voice.channel.connect()

guild = bot.get_guild(guild_id)
if guild and guild.voice_client:
    await guild.voice_client.disconnect()

Debug Mode

Enable debug logging to troubleshoot issues:

import logging

logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

logger = logging.getLogger('salada')
logger.setLevel(logging.DEBUG)

@bot.salad.on('nodeConnect')
def on_connect(node):
    print(f'[DEBUG] Node connected: {node.host}:{node.port}')

@bot.salad.on('nodeError')
def on_error(node, error):
    print(f'[DEBUG] Node error: {error}')

@bot.salad.on('trackStart')
def on_track_start(player, track):
    print(f'[DEBUG] Playing: {track.title}')

Common Async Issues

RuntimeWarning: coroutine was never awaited

player.play()

Solution:

await player.play()

Event Loop Issues

RuntimeError: Event loop is closed

Solution:

import asyncio

async def main():
    await bot.start('TOKEN')

if __name__ == '__main__':
    asyncio.run(main())

State Management Issues

Players Not Restoring After Restart

Solution: Enable state management:

salad = Salad(client, NODES, {
    'enableReconnect': True,
    'stateSaveInterval': 5.0
})

Player State Corruption

Solution: Clear saved states:

await bot.salad.clear_saved_states()

Getting Help

If you’re still experiencing issues:

1. Check the logs - Both your bot logs and Lavalink server logs
2. Update dependencies - Ensure you’re using the latest version of Salada
3. Test with minimal code - Create a simple reproduction case
4. Join our Discord - Get help from the community
5. Open an issue - Report bugs on GitHub with detailed information

When reporting issues, always include:

• Salada version
• Python version
• discord.py version
• Lavalink version
• Complete error messages and traceback
• Minimal reproduction code

Checklist for Common Setup Issues

• Lavalink server is running
• Correct host, port, and password in configuration
• Bot has Connect and Speak permissions
• Discord intents are enabled (voice_states, guilds)
• User is in a voice channel before connecting
• Node is connected before creating players
• All async functions are properly awaited
• Error handling is implemented for search and playback