Troubleshooting

English | 繁體中文

This page covers the failure modes people actually hit when running NextVoiceCord: what you see, why it happens, and what to do about it.

Playback fails, or there is no audio

Symptom: the bot joins the voice channel and shows a track as playing, or reports an error while trying to load one, but no audio comes through, or a given link/search simply will not play at all.

Cause: this project is in beta specifically because of YouTube extraction. Published youtube-source releases currently cannot play a large share of videos, so this build pins an unreleased snapshot that can. That pin is what makes playback work at all right now, but it also means the extraction layer is ahead of anything officially released — it is verified against real playback on every CI run, and the pin is dropped the moment an upstream release passes the same check, but it is not the same guarantee as depending on a stable release.

What to do: if a specific video will not play, try a different source or search term before assuming your setup is broken — this is a known, structural limitation of the current beta, not usually a configuration problem. Check the release notes for the version you are running to see whether the failure you are hitting is already known. If playback fails across the board rather than on specific tracks, treat it as a startup or connection problem instead (see below) rather than the beta caveat.

The bot will not start

Several distinct causes produce different messages; check the console (or desktop alert) for which one you have.

"Invalid configuration. Check your token." — discord.token in config.txt is missing, malformed, or was rejected by Discord. Regenerate the token from the Bot tab of your Discord application and paste it in exactly, then restart.

"Invalid response from Discord. Check your internet connection." — the machine could not reach Discord's servers. Check outbound connectivity and any firewall or proxy in front of it.

"Your bot is missing required Discord intents!" — the bot connected but Discord rejected the session because a privileged intent is not enabled. The message names the fix directly: go to the Bot settings of your application in the Developer Portal and enable Message Content Intent, then restart. This is a one-time setup step per bot application — see Getting-Started.

"Another instance of NextVoiceCord is already running." — the bot takes an exclusive lock on its working directory at startup so two copies pointed at the same config cannot both run (which would otherwise mean every command gets answered twice). If you see this, an earlier process is still alive — check for it before starting another, or wait for it to fully exit. The lock is released automatically when a process exits, including on a crash, so it does not need manual cleanup.

The jar refuses to run at all, with a class-file-version error. — this is the JVM itself refusing to run a jar compiled for a newer Java than the one invoking it. NextVoiceCord requires Java 25 or newer; check java -version and update the runtime if it is older. (The bot's own startup check only confirms you are on a 64-bit JVM — it does not catch an outdated version before the JVM does, so this shows up as a launch failure rather than a friendly message from the bot.)

Port already in use, with --web. — a bind failure on the web panel's port is logged but does not stop the rest of the bot; music playback and the desktop window (if enabled) come up normally, just without the panel. Check the log for the bind error, free the port or choose a different one with --web <port>, and restart.

The web panel is unreachable

Symptom: --web <port> was passed, the bot started, but the panel does not load in a browser.

Cause and fix, in order of likelihood:

• Binding. The panel binds 127.0.0.1 by default — reachable only from the same machine. To reach it from another device on the network, set web.bindAddress = "0.0.0.0" in config.txt. Doing so also means the panel is now reachable by anything else on that network, over plain HTTP, with the token visible to anyone who can see the traffic — do not forward the port to the internet.
• The token. The panel authenticates with a single bearer token that is generated fresh and printed to the console every time the bot restarts. A token from a previous run, or a bookmarked URL from before a restart, will not work — get the current one from the console.
• A write request without the right header. Loading the page works with the token in the URL (?token=…), but anything that changes state — saving config, changing settings, controlling playback from the API — only accepts the token in an Authorization: Bearer <token> header, never in the query string. This is deliberate: a header cannot be forged by a page on another site the way a URL can. If a write is failing with 401 Unauthorized while the page itself loaded fine, this is almost always why.
• Config editing specifically refused. A config write returns 403 with "Config editing is off. Set web.allowConfigEdit = true in config.txt." if that setting is off, which it is by default. Turn it on only if you actually want the panel able to rewrite config.txt — discord.token, web.bindAddress, and web.allowConfigEdit itself can never be changed from the panel regardless.
• Locked out after failed attempts. Repeated bad tokens from the same address get rate-limited with 429 Too many failed attempts. Wait it out, or restart the bot to invalidate the old token and get a fresh one.

The desktop window will not open

If there is no display available — a headless server, a machine over SSH without X forwarding — the desktop window cannot open and the process will hang or fail depending on the environment. Run with --nogui instead, which skips the GUI entirely and logs to the console. Combine it with --web <port> if you still want a UI, just a browser-based one instead of a desktop one.

Commands do not appear in Discord

Symptom: /play and friends are not offered by Discord's slash-command autocomplete, on a server the bot is already in.

Cause: slash commands are registered globally (not per-server), and Discord's own propagation of newly registered or changed global commands to clients is not instant — it can take a while to reach every client after a change. The bot only re-registers when its command set has actually changed since last time (it hashes the set and skips the Discord API call otherwise), so this delay is normally only relevant right after installing the bot for the first time or updating to a version that changed commands.

What to do: wait, and try restarting your Discord client. If commands still do not appear after a reasonable wait, check the console log for a slash-command registration error, and confirm the bot actually has the applications.commands scope from when it was invited — if it was invited with only the bot scope, slash commands cannot be registered for it at all and it needs to be re-invited with both scopes.

Text is in the wrong language, or partly English

Symptom: some replies are in your server's configured language, but a specific message or two shows up in English instead, in an otherwise non-English server.

Cause: this is not a bug in the usual sense. Of the twelve shipped languages (DE, EN, ES, FR, JA, KO, PL, RU, UA, VN, ZH-CN, ZH-TW), only English has been reviewed by a person — the other eleven are machine-generated and each carries _meta.reviewed: false. Translation fallback works per key, not per file: if a particular string has not been translated (or the translation is missing/broken), that one string falls back to English while everything else around it stays in the configured language. Language itself resolves per user first, then per server, then the global default — so the same command can legitimately show different languages to different people in the same channel if they have set personal overrides.

What to do: this is expected behaviour for the eleven unreviewed languages, not a misconfiguration — there is nothing to fix in config.txt. If you speak one of them, a translation review is the single most useful contribution the project can take; see the README's Translations section for where the files live and the rules CI enforces on them.

See also

Getting-Started for initial setup. Controller-Panel if a layout is rendering blank rather than the bot as a whole failing. Commands and Permissions-and-Server-Settings if a command runs but is denied — that is a permissions question, not a bug.