Troubleshooting
Common issues and how to fix them (Programmed by humans!)
Common Problems
A Note on Humanity
NodeLink was recently rewritten from the ground up. While we strive for perfection, we are humans (mostly), and humans make mistakes. If you encounter something that isn't listed here or seems like a bug, please join our PerformanC Discord or Ecliptia Discord and let us know!
Here are specific errors you might encounter in your console or logs, and exactly what they mean.
Startup & Connection Errors
Port Already in Use
Message: Port 3000 is already in use.
Another application (or a zombie instance of NodeLink) is already running on the port you configured.
- Linux/Mac: Run
lsof -i :3000to see what's using it, thenkill -9 <PID>. - Windows: Use Task Manager or
netstat -ano | findstr :3000. - Alternative: Change
server.portin yourconfig.js.
Unauthorized Connection
Message: Unauthorized connection attempt from [IP] - Invalid password provided
Your Lavalink client (the bot) is sending a password that does not match server.password in config.js.
- Check: Ensure both your bot's config and NodeLink's config match exactly.
- Client Name: Some clients fail to send a
Client-Nameheader. NodeLink rejects these connections. Ensure your client library is up to date.
YouTube Specifics
Cipher Server Unavailable
Message: Cipher server at ... is offline or unreachable.
NodeLink relies on a signature deciphering service (like the one hosted by Kikkia) to play YouTube videos.
- Check Config: Look at
sources.youtube.cipher.urlinconfig.js. - Status: The public server might be down. You may need to host your own or find an alternative.
Age Restricted / Login Required
Some videos require a logged-in account. NodeLink attempts to use OAuth tokens if configured, but they can expire.
- OAuth: Set
sources.youtube.getOAuthTokentotruein config, restart, and follow the instructions in the console to refresh your token. - TV Client: We simulate a TV client to bypass some restrictions, but
refreshTokenmust be valid.
Voice & Audio
Voice Connection Not Ready
Message: Voice connection for guild ... is not ready (missing UDP info).
NodeLink connected to Discord's WebSocket, but failed to establish the UDP connection required to send audio.
- Firewall: Ensure your server allows outgoing UDP traffic to high ports.
- Docker: If running in Docker, ensure you aren't blocking UDP.
- Discord: Sometimes Discord's voice servers are just having a bad day.
Decoder / Native Module Issues
NodeLink relies on native modules like sodium-native and opusscript (or others) for encryption and encoding.
- If you see errors related to
sodiumoropus, try reinstalling dependencies:rm -rf node_modules && npm install. - Ensure you have build tools installed (Python, C++ compiler) if you are building from source.
Worker & Process Issues
Worker Died / Crash
If a worker process dies, it usually means something went very wrong internally. NodeLink isolates players in workers, so if a worker fails, it dumps the error and the responsibility back to the main process (and you).
What to do:
- Enable debug logging in
config.js(setlogging.levelto'debug') to catch the stack trace. - This is likely a bug in the core logic. Please copy the logs and report it on our Discord servers.
Configuration & Updates
Missing Configuration Options
NodeLink evolves fast. If you updated the server but forgot to update your config.js, you might be missing critical settings.
Always check the config.default.js file in the root directory after an update. It contains the source of truth for all available options. If an option says it doesn't exist, it probably just needs to be copied over.
Connection & Network
Network Instability
NodeLink includes a recovery system that attempts to handle disconnections gracefully. However, if you see frequent ECONNRESET errors, check your environment:
- Firewalls: Ensure nothing is aggressively terminating long-lived connections or blocking specific packets.
- Router Channels: Some routers automatically switch WiFi channels (frequencies) to "optimize" the network. When this happens (channel 1 → 6, for example), the router often momentarily disconnects all clients to re-establish the link on the new frequency. This brief interruption is enough to kill an active stream.
- YouTube: Sometimes YouTube simply closes the connection. This is "normal" behavior we try to mitigate.
Limits & Protection
Rate Limiting
NodeLink protects itself with a built-in rate limiter and DoS protection system. If you are running a private client that executes many requests in a few seconds (e.g., a dashboard or heavy load testing), you might trigger these protections.
It is recommended to disable rateLimit and dosProtection in your configuration if you trust the clients connecting to your node.