Troubleshooting
Find the layer that failed and fix installation, source, voice, and playback problems.
Find the layer first. A missing source plugin and a native decoder failure are different problems.
Installation and native runtime
Symptom: ERR_DLOPEN_FAILED, a missing .node addon, avcodec or FFmpeg library errors, or missing Windows DLLs.
Check:
- Node.js version and CPU architecture.
- That optional platform packages were installed.
- The five FFmpeg 9 shared libraries and their ABI versions (63, 63, 61, 12, 7).
Run the smoke test. Embedded hosts need the libraries locally. A bot that only uses remote nodes does not.
The generated bot will not start
Symptom: npm run dev exits right away.
Check: the message it prints.
| Message | Cause |
|---|---|
DISCORD_TOKEN is not set | .env is missing. Copy .env.example to .env |
ALLOWED_MEDIA_HOSTS must list bare hostnames | An entry is a URL, has a port or a wildcard. List hostnames only |
Could not log in to Discord | The token is wrong or was reset |
Could not start the audio engine | The FFmpeg 9 shared libraries are missing. See Install FFmpeg |
/play replies that playback is disabled until ALLOWED_MEDIA_HOSTS contains the host of the link. See the generated project.
No tracks found
Symptom: player.search(query) returns no tracks, or a query never starts playback.
Check: the registered plugins, that search.query.match accepts the query, the query prefix, blockExtractors, searchEngine, and search.query.resolve. A track URL alone does not register a source.
Playback fails after a track starts
Symptom: the track resolves but playerError fires when it plays.
Check: that track.stream is registered and returns something playable. For remote nodes, the audio server must be able to reach the URL or file, not only the bot. Check credentials, redirects, and codec support, and read the error attached to the event.
Voice never connects
Check:
- The bot's permissions in the channel.
- The user ID passed to
initialize(). - That
sendreaches the shard that owns the guild. - That every raw gateway packet, including
READY,VOICE_STATE_UPDATE, andVOICE_SERVER_UPDATE, reachesplayer.receive().
Several guilds fail to join at once
Symptom: one guild joins while the others fail with request_timeout or Discord voice close code 4022.
Check: use the same Remedia release for client and server. Confirm that each guild's join request reaches its shard, and that voice packets reach player.receive().
Test with Promise.allSettled. See voice recovery.
Playback stops, skips, or repeats unexpectedly
Check:
- Use
queue.play()for managed tracks, notqueue.node.play(source). - Check the repeat mode.
- Make sure no listener advances the queue from
playerFinish.
See the playback lifecycle.
A legacy extractor breaks
Check: that you registered a BaseExtractor class, and that stream() returns encoded media and not an old voice pipe. If it relies on raw.engine, move it to a public URL or a portable sourceReference.