How to Troubleshoot Common BungeeCord Problems

BungeeCord networks can have unique issues related to proxy configuration, IP forwarding, and multi-server setups. Here are the most common problems and solutions.

Connection Issues

"Could not connect to a default or fallback server"

Cause: The proxy can't reach the backend server listed in priorities.

Fix:

1. Check config.yml on the proxy — verify the backend server address and port are correct
2. Ensure the backend server is running
3. Verify the backend port matches what's configured in the proxy
4. Check Network on the XGamingServer panel for the correct port

"If you wish to use IP forwarding, please enable it in your BungeeCord config"

Cause: Backend has bungeecord: true in spigot.yml but the proxy doesn't have ip_forward: true.

Fix: Edit config.yml on the proxy and set:

ip_forward: true

Then restart the proxy. See IP Forwarding for the full guide.

Players can't switch servers

Cause: Server names in /server <name> don't match config.yml.

Fix: Check the servers section in config.yml. Server names are case-sensitive:

servers:
  lobby:    # /server lobby
    address: 127.0.0.1:25566
  survival: # /server survival
    address: 127.0.0.1:25567

Authentication Issues

"Failed to verify username"

Cause: online-mode settings are incorrect.

Fix:

• Proxy config.yml: online_mode: true
• All backends server.properties: online-mode=false

The proxy handles authentication — backends must have it disabled.

Players can impersonate other users

Cause: No BungeeGuard installed. Anyone connecting directly to a backend can use any username.

Fix: Install BungeeGuard on the proxy and all backends immediately. This is a critical security issue.

Plugin Issues

Plugins not working across servers

Cause: Bukkit/Spigot plugins only work on the individual server they're installed on.

Fix:

• Install BungeeCord plugins in the proxy's /plugins/ folder for cross-server functionality
• Install Bukkit/Spigot plugins on each backend server separately
• For shared data (economy, permissions), use MySQL-backed plugins like LuckPerms with a shared database

Chat not syncing between servers

Fix: Install a BungeeCord chat plugin on the proxy, such as:

• BungeeChat — Cross-server chat
• LunaChat — Multi-language chat support

Performance Issues

Proxy using too much RAM

Fix:

• BungeeCord itself needs very little RAM (512 MB–1 GB is usually enough)
• Don't install heavy plugins on the proxy — keep it lightweight
• Install server-side plugins on backends, not the proxy

High latency between servers

Fix:

• Ensure proxy and backends are on the same network/machine
• Use internal IPs (127.0.0.1 or local network) instead of external IPs in config.yml
• Reduce the number of BungeeCord plugins

Security Checklist

• ip_forward: true on proxy
• bungeecord: true in spigot.yml on backends
• online-mode=false on backends
• online_mode: true on proxy
• BungeeGuard installed on ALL servers
• Backend ports not exposed to public (firewall)

⚠️ Warning: Never expose backend server ports to the internet. Players should only be able to connect through the proxy. Use firewall rules to block direct access.

💡 Tip: If troubleshooting is complex, consider migrating to Velocity which has better error messages and built-in security features.

See also: BungeeCord Guide | IP Forwarding | BungeeGuard

If you need help, join our Discord.