Troubleshooting

Troubleshooting

Most problems are caught by the startup check, which prints what is wrong and how to fix it. This page collects those messages, the errors users see in Discord, and the questions people ask most.

First step for anything strange: set DEBUG=true in .env, restart the bot and read the console. The log usually names the real cause.

---

Before the bot starts

Problem	Fix
'node' is not recognized / command not found: node	Node.js is not installed, or the terminal was opened before installing it. Install it from nodejs.org and open a new terminal.
Node.js X is too old (22.12 or newer is required)	Install the current LTS version from nodejs.org (macOS: brew install node), close the window, open a new terminal and start again.
npm warn allow-scripts ... not yet covered by allowScripts	Harmless. Newer npm versions skip package install scripts; the bot downloads what it needs on start.
npm packages could not be installed	Check the internet connection, then in the bot folder delete node_modules and run npm install (commands below).
Your local changes to .env would be overwritten on git pull	You are updating from v16. See Installation > Updating from v16.

Reinstalling the packages:

# macOS / Linux
rm -rf node_modules
npm install

:: Windows (cmd)
rmdir /s /q node_modules
npm install

---

Startup check messages

Message	What it means and how to fix it
A .env file was created for you, but it still needs your bot token	First start. Open .env and fill in DISCORD_TOKEN.
DISCORD_TOKEN is empty	Put your token into .env: Developer Portal > your bot > Bot > Reset Token.
DISCORD_TOKEN does not look like a bot token	Copy the token again without spaces or quotes. A token has three parts separated by dots.
Discord rejected DISCORD_TOKEN (wrong or reset token)	The token is wrong or was reset. Press Reset Token again and paste the new one.
Could not reach Discord to check the token	The machine cannot reach Discord. Check the internet connection, firewall and proxy settings. (If CLIENT_ID is set, the bot only warns and tries anyway.)
[WARN] CLIENT_ID in .env (...) belongs to another application	Harmless: the bot uses the token's own id. You can delete CLIENT_ID from .env.
GUILD_ID "..." is not a server id	Leave GUILD_ID empty, or put a real server id: turn on Developer Mode in Discord, right-click the server, Copy Server ID.
PROXY_URL "..." is not a valid proxy address	Use the form http://user:password@host:port. Several proxies are separated by commas.
COOKIES_FILE "..." does not exist	The file is not where .env says. The message shows the full path it expected. Export the cookies there (YouTube Access) or remove COOKIES_FILE.
COOKIES_FROM_BROWSER "..." is not a supported browser	Use one of: brave, chrome, chromium, edge, firefox, opera, safari, vivaldi, whale.
Cannot write to .../data	Give your user write permission to the bot folder (or point DATA_DIR to a writable folder).
yt-dlp is missing (needed for YouTube)	The automatic download failed. Check the internet connection and start again, or install yt-dlp yourself (see Installation) and set YTDLP_PATH if it is not on your PATH.
ffmpeg is missing (needed to play any audio)	Same as above for ffmpeg, with FFMPEG_PATH.
Voice libraries do not load	Usually node_modules was copied from another computer. Delete the node_modules folder and start again.
[INFO] Spotify API keys not set	Not an error. Add Spotify keys only if you need playlists with more than 100 songs.
yt-dlp update check failed (will retry on next start)	Only a warning. The current yt-dlp keeps working.
Slash commands could not be registered in GUILD_ID ...: the bot is not in that server	Invite the bot to that server, or leave GUILD_ID empty.

---

In Discord

Problem	Fix
Commands do not show up	Wait a minute and press Ctrl + R in Discord. Check that the bot was invited with the applications.commands scope. If GUILD_ID is set, commands exist only in that server. To force a new registration run npm run deploy (needs CLIENT_ID in .env).
"You must be in a voice channel!"	Join a voice channel first.
"You must be in the same voice channel as the bot!"	The bot is already playing elsewhere in this server. Join its channel, or /stop it first.
"I don't have permission to speak in this voice channel!"	Give the bot View Channel, Connect and Speak in that voice channel.
"That voice channel is full."	Make room, or give the bot Move Members so it can join full channels.
The bot joins but there is no sound	Make sure the bot has Speak, is not server-muted, and check the volume with /volume.
Music plays but no player panel appears	The bot cannot write in that text channel. Give it View Channel and Send Messages there (and Send Messages in Threads in threads).
"No music is currently playing!"	Queue commands need music playing. Start something with /play.
"Search results not found or expired!"	/search results last 10 minutes and only the person who searched can pick. Search again.
"No lyrics found for this song."	LRCLIB has no lyrics for that title. Try /lyrics song: with the artist and title typed out.
"The queue is full (500 songs)." / "Only the first 500 songs were added."	The queue limit was reached. Raise MAX_QUEUE_SIZE if you need more.
A big Spotify playlist stops at 100 songs	Add SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET (Configuration).
The music paused by itself	Everyone left the voice channel. It continues when someone joins again (within LEAVE_ON_EMPTY seconds).
The bot left the voice channel	Nobody was listening for LEAVE_ON_EMPTY seconds, or the queue ended LEAVE_ON_FINISH seconds ago. Change or turn off either in .env.
The queue did not come back after a restart	Saved queues are restored only if they are less than 30 minutes old, the voice channel still exists, and someone is in it when the bot starts.
Buttons on an old panel do nothing	Only the newest panel works. Old ones turn into a "Music Ended" card when pressed. Use /nowplaying to bring the current panel to the bottom.

---

Playback errors

Users see	Cause	Fix
YouTube blocked this request (bot detection)	YouTube blocks the server's IP address	Cookies, PO token or proxy: YouTube Access
Audio stream failed	The song was found but the audio could not start. The console shows the real reason next to it.	HTTP Error 403 or "Sign in to confirm" means YouTube blocks this IP: see YouTube Access. Otherwise try the song again or another version.
Songs play from SoundCloud instead of YouTube	YouTube refused them; the console says why (usually a blocked IP)	Fix YouTube access. To get the error instead, set YOUTUBE_FALLBACK=off.
Age-restricted video	YouTube needs a logged-in account	COOKIES_FILE; and the panel's channel must be age-restricted (NSFW)
Geo-blocked content	Not available where the bot is hosted	Another link, or a proxy
Too many requests (rate limited)	A platform is limiting the server	Wait a few minutes; if it repeats, cookies or a proxy
Network error	The bot could not reach the music site	Usually temporary; check the server's connection if it persists
Video unavailable	The video is private, deleted or not available in this area	Try a different song or link
Missing voice channel permissions	The bot may not join or speak in your voice channel	Give the bot Connect and Speak in that channel's permissions
No valid tracks found in the playlist	The playlist is empty, or every song in it is unavailable or age-restricted	Try another playlist
That link is not supported.	No plugin can play that link	Try a different link
No results found!	The search found nothing	Try other words, or a link
Failed to connect to voice channel!	Joining the voice channel did not work	Check the bot's voice permissions and try again
Track could not be played! (posted in the channel)	A song failed while the queue was playing; the reason follows below it	Use the matching row above
An unexpected error occurred	Anything else	Look at the console: the error is logged there. DEBUG=true adds DisTube and ffmpeg details.

Songs take long to start? The console prints one line per song, for example Playing "..." from youtube: found in 3.4s, audio after 4.6s. Finding a YouTube song normally takes 2-4 seconds. If it is much slower, check the server's connection or use PROXY_URL. The very first start also downloads yt-dlp and ffmpeg once.

---

FAQ

Do I need to install Python, ffmpeg or yt-dlp? No. yt-dlp (a build that needs no Python) and ffmpeg are downloaded automatically. You can still use your own with YTDLP_PATH / FFMPEG_PATH.

Do I need to enable Privileged Gateway Intents? No. The bot only uses the Guilds and GuildVoiceStates intents.

Does it need a database? No. Server languages and saved queues are small JSON files in data/.

Does it download songs to disk? No. Music is streamed. The old audio_cache folder from v16 is deleted automatically.

Can the volume go above 100? No. Volume is 0-100, and DEFAULT_VOLUME is kept between 1 and 100.

Does it work in direct messages? No. All commands are server-only.

How many servers can it handle? Sharding is always on. With TOTAL_SHARDS=auto the bot starts as many shards as Discord recommends and restarts crashed ones.

Can I run it on a hosting panel? Yes. Set DISCORD_TOKEN (and any other setting) as environment variables and use npm start or node index.js. See Deployment.

How do I change the language? Use /language (needs Manage Server). Without it, replies follow each user's Discord language. To change the fallback for everything, set DEFAULT_LANGUAGE.

Can I change the bot's color and status text? Yes: EMBED_COLOR and STATUS in .env.

Is there a Docker image or a web dashboard in this repository? No. The repository contains the bot itself. The web dashboard at beatra.app belongs to the public Beatra bot.

Where do I report a bug? See Contributing.

---

Still stuck? Open an issue on GitHub with the console output (remove your token first).