Skip to content

Troubleshooting

Jump to bottom
Fed43 edited this page Oct 10, 2026 · 1 revision

Troubleshooting

Common problems and their solutions when running MineAlphaProxy.

How to Read This Page

Find your error message, apply the fix. If nothing here helps:

  1. Enable verbose logging in core.yml (future feature) or check the console output
  2. Open an issue: https://github.com/MineAlphaStudio/MineAlphaProxy/issues
  3. Attach the full console log (from startup to error) and your core.yml (redact secrets)

Startup Errors

"Error: Could not find or load main class .encoding=UTF-8"

Cause: Running the JAR from PowerShell with unquoted -D arguments. PowerShell splits -Dfile.encoding=UTF-8 into two separate tokens.

Fix: Use run.bat on Windows, or quote each argument:

java "-Dfile.encoding=UTF-8" "-Dstdout.encoding=UTF-8" -jar MineAlphaProxy-1.0.1-ALPHA.jar

Or use the argument array in PowerShell:

$args = @("-Dfile.encoding=UTF-8", "-Dstdout.encoding=UTF-8", "-jar", "MineAlphaProxy-1.0.1-ALPHA.jar")
& java $args

"Unsupported class file major version 68"

Cause: The bundled ViaProxy.jar was compiled with a newer Java version than your Gradle Shadow plugin can process.

Fix: This is already handled by the build - ViaProxy is stored as ViaProxy.bin (opaque) so Gradle does not process it. If you still see this error, check build.gradle.kts - the copyViaProxy task must copy to ViaProxy.bin, not ViaProxy.jar.

"Address already in use: bind"

Cause: Port 25577 (or 25576 for ViaProxy) is already in use by another process.

Fix: Find the process and kill it, or change the port.

Windows:

netstat -ano | findstr :25577
taskkill /PID <pid> /F

Linux:

sudo lsof -i :25577
sudo kill <pid>

Or change the port in core.yml:

bind:
  port: 25578

"forwarding.mode=modern, but file forwarding.secret not found"

Cause: The secret file was deleted or renamed.

Fix: Either restore the file or let MineAlphaProxy generate a new one.

Option 1 - regenerate:

  1. Delete forwarding.secret
  2. Restart MineAlphaProxy - it will create a new one
  3. Copy the new value to every backend's paper-global.yml
  4. Restart backends

Option 2 - switch to none while testing:

forwarding:
  mode: "none"

Not recommended for production - the backend will not see the real player IP.

"Invalid proxy-name: 'X'. Allowed values: [Fed43Proxy, MineAlphaProxy]"

Cause: proxy-name in core.yml is set to something other than the two allowed brands.

Fix: Edit core.yml:

proxy-name: "MineAlphaProxy"

Or:

proxy-name: "Fed43Proxy"

Then restart.

"Section servers.list is empty"

Cause: No backend servers are configured.

Fix: Add at least one server to core.yml:

servers:
  list:
    lobby: "127.0.0.1:25566"

And set default-server to match:

default-server: "lobby"

Console Errors

Unknown command

Cause: The command does not exist in the console dispatcher.

Fix: Check /help for a full list. Commands from plugins are only available if the plugin registered them and loaded successfully.

"ViaVersion has not loaded the platform yet"

Cause: You have ViaVersion-*.jar or ViaBackwards-*.jar in VelocityPlugins/ and MineAlphaProxy tried to load them directly. ViaVersion requires special integration that is only provided through the ViaProxy child process.

Fix: Move ViaVersion and ViaBackwards out of VelocityPlugins/:

Move-Item VelocityPlugins/Via*.jar _disabled/

They are already bundled inside ViaProxy - do not load them as plugins.

"Failed to load Velocity plugin X: NoClassDefFoundError: com/velocitypowered/api/..."

Cause: The plugin uses a class from Velocity's API that MineAlphaProxy does not implement.

Fix: This plugin is not compatible. Options:

  1. Check if a MineAlpha version exists
  2. Open an issue with the missing class name
  3. Disable the plugin

Common missing classes:

Class Feature
com.velocitypowered.api.command.BrigadierCommand Brigadier command system
com.velocitypowered.api.proxy.messages.ChannelMessageSink Plugin messaging
com.velocitypowered.api.proxy.server.RegisteredServer Server registry (partial)
com.velocitypowered.api.event.ResultedEvent.* Cancellable events

"Failed to load MineAlpha plugin: no minealpha-plugin.yml"

Cause: The JAR does not contain a minealpha-plugin.yml descriptor.

Fix: If the plugin targets Velocity, place it in VelocityPlugins/ instead. If it is your own plugin, add minealpha-plugin.yml to src/main/resources/.

Encoding Issues

Console shows "??????" or box characters instead of Cyrillic

Cause: Terminal encoding mismatch.

Fix (Windows):

Launch through run.bat which includes:

chcp 65001 >nul
java -Dfile.encoding=UTF-8 -Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8 -jar MineAlphaProxy-1.0.1-ALPHA.jar

Or set the code page manually before starting:

chcp 65001
java -Dfile.encoding=UTF-8 -jar MineAlphaProxy-1.0.1-ALPHA.jar

Recommended: use Windows Terminal instead of cmd.exe - it supports UTF-8 out of the box.

Fix (Linux):

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

MOTD shows correct symbols on one server, question marks on another

Cause: The other server's MOTD is not saved in UTF-8.

Fix: Open core.yml in a UTF-8 aware editor (Notepad++, VS Code, Sublime) and re-save as UTF-8 without BOM.

Connection Issues

"Unable to verify player details"

The client received a Login Success with a UUID that does not match what it sent.

Causes and fixes:

  1. Backend has proxies.velocity.online-mode: false

    Edit paper-global.yml:

    proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: "YOUR_SECRET"

    Restart the backend.

  2. Client and backend versions differ

    Enable ViaProxy (see ViaProxy) and connect to port 25576.

  3. Forwarding data is malformed

    Check the proxy log:

    Backend disconnected player: "Unable to verify player details"

    If this appears immediately, the forwarding payload is malformed. Ensure you are on 1.0.1-ALPHA or newer.

"Backend requested encryption"

Cause: The backend has proxies.velocity.enabled: false and expects to encrypt the connection itself.

Fix:

proxies:
  velocity:
    enabled: true

Restart the backend (full restart, not /reload).

Client stuck on "Connecting to the server..."

Cause: The proxy is reachable but the backend is not.

Fix: Check the proxy log:

Connecting to backend 'lobby' (127.0.0.1:25566)...
Backend 'lobby' (127.0.0.1:25566) unavailable: Connection refused

Verify the backend is running and the address in core.yml is correct.

"Connection refused" on port 25576

Cause: ViaProxy is not running.

Fix: Check the ViaProxy log:

Get-Content "$env:TEMP\minealpha-viaproxy\viaproxy.log" -Tail 50

If the log is missing, ViaProxy was never extracted. Ensure the built JAR contains viaproxy/ViaProxy.bin:

Add-Type -AssemblyName System.IO.Compression.FileSystem
$jar = [System.IO.Compression.ZipFile]::OpenRead("build\libs\MineAlphaProxy-1.0.1-ALPHA.jar")
$jar.Entries | Where-Object { $_.FullName -like "*viaproxy*" } | Select-Object FullName
$jar.Dispose()

If nothing prints, rebuild with ViaProxy in libs/.

Performance Issues

High CPU usage

Causes:

  1. Many players connecting through ViaProxy (packet translation is CPU-intensive)
  2. Plugin loop without delay
  3. Log spam

Fixes:

  • Check plugins that use runAsyncRepeating with 0 delay
  • Reduce logging level in core.yml (future feature)
  • Consider running ViaProxy on a separate machine

High memory usage

Cause: Default JVM heap may be too small or too large for the player count.

Fix: Set heap explicitly:

java -Xms1G -Xmx4G -jar MineAlphaProxy-1.0.1-ALPHA.jar

Rule of thumb: 512 MB + 1 MB per concurrent player.

Plugin Issues

Plugin loads but its commands do nothing

Cause: Commands registered by plugins are only dispatched from the console in 1.0.1-ALPHA. In-game command routing requires additional setup.

Fix: Use the console to test the command first. In-game support is planned.

Plugin data folder is empty

Cause: The plugin never called saveResource(...) or wrote files to getDataFolder().

Fix: This is expected. The folder exists but stays empty until the plugin writes to it.

Plugin logger shows nothing

Cause: SLF4J provider is missing or plugin uses its own logger.

Fix: MineAlphaProxy provides its own SLF4J provider. If a plugin does not log, check the console for SLF4J(W): No SLF4J providers were found. - this means the provider failed to load.

ViaProxy Issues

"Invalid target server version. Defaulting to auto detect."

Cause: ViaProxy cannot determine the backend version and falls back to auto-detection.

Fix: This is a warning, not an error. ViaProxy will detect on the first connection. To silence, set the exact version in ViaProxyLauncher.java:

"target-version: 1.21.4\n"

Rebuild and restart.

ViaProxy output interleaved with proxy output

Cause: Old versions of MineAlphaProxy used inheritIO(). New versions redirect ViaProxy output to a log file.

Fix: Update to the latest 1.0.1-ALPHA or newer, and delete the temp folder so the change takes effect:

Remove-Item "$env:TEMP\minealpha-viaproxy" -Recurse -Force

Commands typed in console go to ViaProxy

Cause: ViaProxy reads from stdin.

Fix: Ensure ViaProxyLauncher.java uses:

File nul = new File("NUL");  // Windows
pb.redirectInput(ProcessBuilder.Redirect.from(nul));

On Linux, use /dev/null instead:

File nul = new File("/dev/null");

Recovering from Bad State

Config is broken - proxy won't start

Delete core.yml and restart. It will be recreated from the template:

Remove-Item core.yml
java -jar MineAlphaProxy-1.0.1-ALPHA.jar

Warning: Servers, MOTD, and other custom settings are lost.

Plugin prevents startup

Move the plugin out of MineAlphaPlugins/ and restart:

Move-Item MineAlphaPlugins/SuspectPlugin.jar _disabled/

If the proxy starts, that plugin is the culprit. Check the log for the exact error.

Secret leaked to Git

If forwarding.secret was accidentally committed:

  1. Rotate the secret immediately (delete, regenerate, update all backends)

  2. Remove the file from Git history:

    git rm --cached forwarding.secret
git commit -m "Remove leaked secret"
git push

    For full history removal, use git filter-repo or BFG Repo-Cleaner.

  3. Force all backends to use the new secret

Getting Help

If your issue is not here:

  1. Check the FAQ - many questions are already answered
  2. Open an issue: https://github.com/MineAlphaStudio/MineAlphaProxy/issues
  3. Include:
    • Full console log (startup to error)
    • Your core.yml (redact forwarding.secret)
    • MineAlphaProxy version
    • Java version (java -version)
    • OS
    • List of loaded plugins
    • Steps to reproduce

Next Steps

Clone this wiki locally