Troubleshooting Lavalink: Common Errors and Fixes

When a music bot misbehaves, the problem can be in the bot, the client library, the Lavalink node, a source like YouTube, or the network between them. This guide groups the most common Lavalink problems by symptom and gives the fix for each.

Two tools make diagnosis much faster:

• The Lavalink log. On a systemd install, journalctl -u lavalink -f; in Docker, docker logs -f lavalink; on managed hosting, ask support for node-side details.
• Your client’s events. Log node connect/disconnect/error events and every track exception with its message.

Connection problems

ECONNREFUSED / connection refused

Nothing is listening at the address and port your bot is using.

• Is Lavalink running? Check the log for “Lavalink is ready to accept connections.”
• Is the port right? It must match server.port in application.yml (usually 2333).
• Is Lavalink listening on the right interface? server.address: 127.0.0.1 only accepts local connections; use 0.0.0.0 if the bot is on another server.
• Is a firewall blocking the port? Allow your bot’s IP to reach it.

401 Unauthorized

The password in your bot doesn’t match lavalink.server.password. Check for stray spaces or quotes in environment variables.

Timeouts

The node exists but is unreachable from your bot’s network — a firewall, wrong IP or DNS issue. Test from the bot’s server with curl -H "Authorization: <password>" http://<node>:2333/version.

The node keeps disconnecting

Look for crashes in the Lavalink log (often out-of-memory errors — see below), network instability between bot and node, or a node being restarted for updates. Enable session resuming so brief drops don’t end playback.

The bot joins, but there’s no sound

This is the most common complaint. Work through these in order:

1. Voice states intent. Your bot needs the GuildVoiceStates intent (discord.js) or voice_states (discord.py, included in default intents). Without it, the client never forwards voice updates to Lavalink.
2. Permissions. The bot needs Connect and Speak in that channel.
3. Track exceptions. Check your logs. The track may have failed to load or play — often a source issue (see the next section).
4. Outbound UDP. Lavalink sends audio to Discord voice servers over UDP. A firewall on the node that blocks outbound UDP causes silent players even though everything else works. Allow outbound UDP.
5. The player isn’t actually playing. Log the result of your play call and the player state. It’s easy to resolve a track and never call play.

Track loading problems

Lavalink v4 returns a loadType for every load: track, playlist, search, empty or error.

• empty — nothing matched. Try a different query or source prefix.
• error — the source failed. The response includes an exception message and severity; log it.

YouTube errors

Messages like “Sign in to confirm you’re not a bot”, “This video requires login”, cipher or signature errors, and 403s during playback almost always mean the YouTube source needs attention. First step: update the YouTube plugin to the latest release and restart. Also make sure the built-in source is disabled (sources.youtube: false) so it doesn’t conflict with the plugin. Details in the YouTube source plugin.

Spotify links fail

LavaSrc needs valid Spotify credentials to fetch metadata. If metadata resolves but playback fails, the problem is the source the track is mirrored to — usually YouTube. See LavaSrc explained.

Playlists load slowly or time out

Large playlists create a lot of work. Lower youtubePlaylistLoadLimit and LavaSrc’s playlistLoadLimit, and in your bot, start playing the first track while the rest load.

Playback problems

TrackStuckEvent

No audio was produced for longer than trackStuckThresholdMs. Causes include a slow or stalled source stream and an overloaded node. Handle the event in your bot by skipping to the next track, and check CPU if it happens often.

Stuttering or robotic audio

• CPU starvation. Check /v4/stats: high lavalinkLoad and rising frame deficit mean the node can’t keep up. Reduce filters, lower resamplingQuality or opusEncodingQuality, or give the node more CPU — see how much RAM Lavalink needs.
• Garbage collection pauses. Frequent GC warnings in the log point to a heap that’s too small or a poorly suited collector — see JVM tuning for Lavalink.
• Distance. A node far from the voice server gives listeners jittery audio. See choosing a Lavalink region.

Playback stops when the bot restarts

Enable session resuming in your client with a timeout longer than your bot’s restart time, and persist queues if they must survive longer outages.

Voice disconnects with close codes

Discord voice connections close with codes your client may log:

• 4014 — the bot was disconnected from the channel (kicked, moved or the channel was deleted). Clean up the player.
• 4006 — the voice session is no longer valid. Rejoin the channel.

Startup problems

UnsupportedClassVersionError

Lavalink v4 needs Java 17 or newer. Check java -version and install a newer JDK.

YAML errors

application.yml is whitespace-sensitive. Use spaces (never tabs), check that nested keys line up, and quote values containing special characters like : or #. An online YAML validator quickly finds the bad line.

A plugin fails to load

The plugin version doesn’t match your Lavalink major version, the repository URL is wrong, or the node can’t reach the Maven repository to download it. Check the startup log for the specific error.

BindException: Address already in use

Another process — often an old Lavalink instance — is using the port. Stop it (sudo ss -ltnp | grep 2333 shows what’s listening) or change the port.

Memory problems

OutOfMemoryError: Java heap space

The heap is too small for the load. Raise -Xmx within your server’s limits, reduce playlist load limits, and check for unusual plugin behaviour.

The process disappears without an error

The whole JVM exceeded the server or container’s memory limit — usually because -Xmx was set too close to total RAM, leaving no room for non-heap memory. Lower the heap to about 70–75% of RAM.

When to ask for help

If you’ve worked through the list and the node still misbehaves, gather:

• the Lavalink version and plugin versions,
• the relevant log lines around the failure,
• a track or query that reproduces it,
• your client library and version.

On Kerit Cloud’s managed Lavalink, node-side issues are handled by the team; open a ticket on Discord with the details above. On self-managed plans, the server is yours, and these notes should cover most situations.

Summary

Connection failures come down to address, port, password and firewall. Silent players are usually missing voice intents, missing Speak permission, track exceptions or blocked outbound UDP. Loading errors are mostly source problems — update the YouTube plugin first. Stutters point to CPU, GC or distance; startup failures to Java version, YAML or plugin mismatches; and vanishing processes to a heap set too close to total RAM.