Troubleshooting Guide

❌ Issue 1: "Server Offline" Error

Cause

Server name in config.toml doesn't match the name in velocity.toml

Solution: Verify Server Names

Step 1: Check Velocity Configuration

# Location: Velocity/velocity.toml
[servers]
hub = "127.0.0.1:25566"
Survival = "127.0.0.1:25567"  # Note: Capital S!
minigames = "127.0.0.1:25568"

Step 2: Match Names Exactly in Config

# Location: Velocity/plugins/velocitynexus/config.toml
[servers.hub]  # ✓ Matches exactly
display-name = "HUB"
enabled = true

[servers.Survival]  # ✓ Capital S matches!
display-name = "SURVIVAL"
enabled = true

[servers.minigames]  # ✓ Matches exactly
display-name = "MINIGAMES"
enabled = true

Verification Steps

1. Open Velocity/velocity.toml
2. Note the exact spelling and capitalization of each server name
3. Open Velocity/plugins/velocitynexus/config.toml
4. Update the name field to match exactly
5. Run /velocitynexus reload or restart
6. Test the GUI again

❌ Issue 2: GUI Not Opening / "Internal Server Error"

Cause

Most Common: Backend plugin is missing on the current server

Solution: Verify Backend Plugin Installation

Step 1: Check Plugin List on Backend Server

On the Spigot/Paper server console (NOT Velocity), run:

plugins

You should see:

Plugins (5): VelocityNexusBackend, OtherPlugin1, OtherPlugin2, ...

Step 2: Install Backend Plugin

1. Download velocitynexus-spigot.jar from download page
2. Place it in SpigotServer/plugins/ folder
3. Restart the Spigot/Paper server
4. Verify with plugins command again

Step 3: Install on ALL Backend Servers

Other Possible Causes

• Plugin failed to load (check console for errors)
• Incompatible Minecraft version
• Plugin messaging not enabled in Velocity config

❌ Issue 3: Items Not Showing in GUI

Cause

Invalid or incompatible material names in config.toml

Solution: Fix Material Names

Common Material Name Issues

material = "RED_BED"      # Wrong in 1.16
material = "NETHER STAR"   # No spaces!
material = "minecraft:grass_block"  # No namespace!
material = "GrassBlock"    # Wrong case!
material = "bed"           # Too generic!

material = "BED"           # Correct for 1.16
material = "NETHER_STAR"   # Underscore!
material = "GRASS_BLOCK"   # No namespace
material = "GRASS_BLOCK"   # Uppercase with underscore
material = "WHITE_BED"     # Specific color

Version-Specific Materials

How to Find Valid Material Names

1. Check Spigot Material Javadocs
2. Look for your Minecraft version (e.g., 1.16.5, 1.20)
3. Copy the exact material name (all caps, underscores)
4. Use in your config.toml

❌ Issue 4: "You are already connected to this server"

Cause

This is expected behavior - Velocity prevents connecting to the same server twice

Why This Happens

• Player is on "hub" and clicks "hub" in the GUI
• Player types /server hub while already on hub
• This is a safety feature from Velocity

Solution (If Desired)

To test with multiple servers:

1. Connect to server A
2. Open GUI with /server
3. Click on server B (different server)
4. Connection should work!

❌ Issue 5: Config Not Reloading / Changes Not Applied

Solution 1: Check Reload Command

/velocitynexus reload

Make sure you're running this on the Velocity proxy console, not a backend server!

Solution 2: Verify Config Syntax

TOML syntax errors prevent config from loading:

title = Server Selector  # Missing quotes!
rows = "3"               # Shouldn't be string
name = hub               # Missing quotes!

title = "Server Selector"  # Quoted string
rows = 3                   # Number
name = "hub"               # Quoted string

Solution 3: Full Restart

Some changes require a full restart:

1. Stop Velocity proxy
2. Wait 5 seconds
3. Start Velocity proxy
4. Test the GUI again

Solution 4: Check Console for Errors

Look for error messages after reloading:

[ERROR] Failed to load config: Invalid TOML syntax at line 15

❌ Issue 6: Permission Errors

Solution: Grant Base Permission

Using LuckPerms

# Give everyone access to /server
/lp group default permission set velocitynexus.server true

# Give specific user access
/lp user PlayerName permission set velocitynexus.server true

Verify Permission

/lp user PlayerName permission check velocitynexus.server

Admin Permission Issues

If admins can't reload:

/lp user YourUsername permission set velocitynexus.admin true

🔧 Complete Debug Checklist

Work through this checklist systematically:

1. Verify Plugin Installation

• Run /plugins on Velocity → See "VelocityNexus"
• Run plugins on EACH backend server → See "VelocityNexusBackend"
• Both plugins show as GREEN (enabled)

2. Check Configuration Files

• Config file exists at Velocity/plugins/velocitynexus/config.toml
• Server names match velocity.toml exactly (case-sensitive)
• No TOML syntax errors
• Material names are valid for your Minecraft version

3. Verify Permissions

• Players have velocitynexus.server permission
• Admins have velocitynexus.admin permission (for reload)
• Per-server permissions set correctly (if using them)

4. Test Functionality

• Type /server → GUI opens
• GUI shows all configured servers
• Clicking server connects successfully
• Player counts show correctly

5. Check Console Logs

• No errors during plugin load
• No errors when opening GUI
• No errors when clicking servers