Skip to main content

​
Troubleshooting

This guide covers common issues you may encounter when running Lavalink and how to resolve them. If Lavalink fails to start, work through these checks:
1

Verify Java version

Ensure you have Java 17 or higher installed:
java -version
If you don’t have Java 17+, download it from Azul Zulu.
2

Check Lavalink version

Make sure you have downloaded the latest Lavalink.jar from the GitHub releases page.Verify the file is not corrupted by checking its size and ensuring the download completed successfully.
3

Validate configuration

Check your application.yml file for syntax errors. Common issues include:
  • Incorrect indentation (YAML requires consistent spacing)
  • Missing required fields
  • Invalid values
See the Configuration documentation for proper formatting.
4

Check port availability

Ensure the port Lavalink is configured to use (default: 2333) is not already in use:
lsof -i :2333
If another process is using the port, either stop that process or configure Lavalink to use a different port.
5

Verify firewall settings

If you’re using a firewall, ensure the port Lavalink uses is open:
sudo ufw allow 2333
If you’re still having issues, check the startup logs for specific error messages.

​
Docker-Specific Issues

If you’re running Lavalink in Docker:

​
Container exits immediately

Check the container logs: 
docker compose logs lavalink
Common causes:
  • Configuration file not found or invalid
  • Permission issues with mounted volumes
  • Incorrect user/group ID in volume permissions

​
Fix volume permissions

Ensure directories have the correct permissions for the Docker user: 
# For Alpine variant (user ID 322)
sudo chown -R 322:322 ./plugins

# For Distroless variant (user ID 65534)
sudo chown -R 65534:65534 ./plugins

​
Configuration file not found

Verify the volume mount in your compose.yml: 
volumes:
  - ./application.yml:/opt/Lavalink/application.yml
Make sure application.yml exists in the same directory as your compose.yml.

​
Systemd-Specific Issues

If you’re running Lavalink as a systemd service:

​
Service fails to start

Check the service status: 
sudo systemctl status lavalink
View detailed logs: 
sudo journalctl -u lavalink -n 50
Common issues:
  • Incorrect paths in the service file
  • User doesn’t have permission to access Lavalink files
  • Java not in the system PATH

​
Fix file permissions

sudo chown -R youruser:youruser /path/to/lavalink
Replace youruser with the user specified in your service file.

​
Service file changes not applied

After modifying the service file, always reload systemd: 
sudo systemctl daemon-reload
sudo systemctl restart lavalink
If Lavalink starts but won’t play audio or connect to Discord voice channels:
1

Verify voice server data

Ensure you’re forwarding the sessionId, token, and endpoint from Discord to Lavalink via the player update endpoint.These values come from Discord’s VOICE_SERVER_UPDATE and VOICE_STATE_UPDATE events.
2

Check bot permissions

Verify your bot has the following Discord permissions:
  • CONNECT - Join voice channels
  • SPEAK - Transmit audio
  • USE_VAD - Use voice activity detection
3

Verify region compatibility

Some Discord voice regions may have connectivity issues. Try a different voice region if possible.
4

Check network connectivity

Ensure Lavalink can reach Discord’s voice servers. Check for:
  • Firewall rules blocking outbound UDP traffic
  • Network restrictions in your hosting environment
  • VPN or proxy interference

​
Enabling Detailed Logging

For troubleshooting, enable more detailed logging by adding this to your application.yml:
application.yml
logging:
  level:
    root: INFO
    # Set this to DEBUG to enable more detailed logging from Lavalink
    lavalink: DEBUG
    # Set this to TRACE to see all WebSocket messages sent
    lavalink.server.io.SocketContext: TRACE
    # Log all track exceptions (COMMON, SUSPICIOUS & FAULT)
    com.sedmelluq.discord.lavaplayer.tools.ExceptionTools: DEBUG
    # Log YouTube Plugin stuff (only needed if you have issues with YouTube)
    dev.lavalink.youtube: DEBUG
    # Log Koe internals (only needed if you have issues with Koe/DAVE)
    moe.kyokobot.koe.internal.dave: TRACE
    moe.kyokobot.koe.internal.gateway: TRACE

  # This will log all requests to the REST API
  request:
    enabled: true
    includeClientInfo: true
    includeHeaders: false
    includeQueryString: true
    includePayload: true
Log levels from most to least verbose:
  1. TRACE - Very detailed, includes all operations
  2. DEBUG - Detailed information for debugging
  3. INFO - General informational messages (default)
  4. WARN - Warning messages
  5. ERROR - Error messages only
  6. OFF - No logging
TRACE and DEBUG levels can generate large log files. Use them only for troubleshooting and switch back to INFO for production.

​
Audio Playback Issues

​
Audio is choppy or stuttering

  • Increase memory allocation: Add more RAM with -Xmx flag
  • Check CPU usage: Ensure the server isn’t overloaded
  • Network latency: Test connection between Lavalink and Discord

​
Audio cuts out randomly

  • Enable auto-reconnect: Ensure your client library handles reconnection
  • Check network stability: Look for packet loss or connection drops
  • Review logs: Look for exceptions or connection errors

​
No audio but no errors

  • Verify volume: Check that volume isn’t set to 0
  • Check filters: Ensure no filters are muting audio
  • Test with different sources: Try a different audio source to isolate the issue

​
Plugin Issues

​
Plugins not loading

Check the plugins directory configuration in application.yml: 
plugins:
  - dependency: "group:artifact:version"
    repository: "https://maven.example.com/releases"
Ensure:
  • The plugins directory exists and is writable
  • Plugin JAR files are in the correct location
  • Plugins are compatible with your Lavalink version

​
Plugin errors on startup

View startup logs for plugin-specific errors: 
java -jar Lavalink.jar
Common issues:
  • Plugin version incompatibility
  • Missing dependencies
  • Conflicting plugins

​
Reverse Proxy Issues

If you’re using a reverse proxy (Nginx, Apache, Caddy):

​
WebSocket connection fails

Ensure WebSocket headers are properly forwarded. For Nginx: 
location / {
    proxy_pass http://localhost:2333;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $host;
}

​
Connection timeouts

Increase proxy timeout values: 
proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;

​
Getting Help

If you’re still experiencing issues after trying these solutions:

FAQ

Check the FAQ for common questions

Discord Support

Join the Lavalink support Discord

GitHub Discussions

Ask questions in GitHub Discussions

Report a Bug

Report bugs on the issue tracker

​
Providing Helpful Information

When asking for help, include:
  • Lavalink version: Check with curl http://localhost:2333/version
  • Java version: Run java -version
  • Operating system: Linux, Windows, macOS, and version
  • Deployment method: Binary, Docker, or Systemd
  • Relevant logs: Include error messages and stack traces
  • Configuration: Share your application.yml (remove sensitive data like passwords)
  • Steps to reproduce: What you did before the issue occurred
This information helps maintainers and community members diagnose your issue quickly.

Build docs developers (and LLMs) love

Get started for freeTalk to us