How to Troubleshoot Common BungeeCord Problems on Your Minecraft Network

BungeeCord networks fail in characteristic ways: misconfigured backends, broken forwarding, missing security plugins, and plugin/server-type confusion. This guide groups the most common issues by symptom and walks through the fix for each.

Quick Triage

Connection Issues

"Could not connect to a default or fallback server"

The proxy can't reach the backend(s) in priorities in config.yml.

Fix:

servers:
  lobby:
    address: 123.45.67.89:25566
    motd: "Lobby"
    restricted: false

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

The backend has bungeecord: true in spigot.yml, but the proxy doesn't have ip_forward: true.

Fix: Set ip_forward: true in the proxy's config.yml and restart the proxy. See IP Forwarding.

Players can't switch with /server <name>

/server requires the exact server name from config.yml, and names are case-sensitive.

Fix:

servers:
  lobby:    # /server lobby
    ...
  Survival: # /server Survival (capital S!)
    ...

Use lowercase names to avoid this entirely. Also verify restricted: false for servers everyone should access.

Backend rejects proxy connections

The backend's BungeeGuard token doesn't match the proxy's.

Fix: Copy the token from the proxy's plugins/BungeeGuard/config.yml to every backend's plugins/BungeeGuard/config.yml under allowed-tokens. Restart all servers.

Authentication Issues

"Failed to verify username"

online-mode is configured incorrectly.

Fix:

The proxy authenticates with Mojang. Backends trust the proxy and skip authentication.

Anyone can join as any username

This is the most dangerous misconfiguration. Without BungeeGuard, the proxy's online-mode=false requirement on backends means anyone who knows a backend IP can connect directly and impersonate any player, including admins.

Fix immediately:

1. Firewall the backend ports so only the proxy can reach them
2. Install BungeeGuard on the proxy AND every backend
3. Use the same token across all servers
4. Or migrate to Velocity with modern forwarding (built-in security)

Plugin Issues

Plugins don't work across servers

BungeeCord and Bukkit/Spigot plugins are two different things. They install in different folders and serve different purposes.

A plugin built for Bukkit will not load on the BungeeCord proxy, and vice versa. Check the plugin's description before installing.

Cross-server chat doesn't sync

Vanilla and Bukkit chat is per-server. To make chat global across the network:

Install on the proxy, then configure to relay messages to backends.

Permissions don't sync between backends

LuckPerms (or any permission plugin) needs a shared MySQL database to sync permissions across multiple backends.

Fix: Install LuckPerms on every backend, point them all at the same MySQL database. See Set Up LuckPerms and Use MySQL Database.

Performance Issues

Proxy uses too much RAM

BungeeCord itself is lightweight — usually 512 MB to 1 GB is plenty.

Fix:

1. Don't install heavy plugins on the proxy (those belong on backends)
2. Limit BungeeCord plugins to network-essential ones (chat, teleport, friends)
3. Set -Xmx1G in the startup args

High latency between proxy and backends

If players experience lag when switching servers:

Fix:

• Host proxy and backends in the same datacenter / region
• Use private/internal IPs in config.yml if all servers are on the same network
• Reduce the number of cross-server plugins
• Avoid running heavy compute on the proxy

Backend servers can be reached directly

Players bypassing the proxy is a critical security issue.

Fix:

1. Firewall backend ports so only the proxy IP can connect
2. Install BungeeGuard so backends reject non-proxy connections
3. Use a private network between proxy and backends if possible
4. Never advertise backend IPs publicly

Final Security Checklist

• ip_forward: true on proxy
• bungeecord: true in every backend spigot.yml
• online_mode: true on proxy
• online-mode=false on every backend
• BungeeGuard installed on proxy AND every backend
• Token matches across all servers
• Backend ports firewalled / not publicly reachable
• Recent backups of all servers

Migrate to Velocity if any of this feels fragile. Velocity has built-in modern forwarding, better error messages, no need for BungeeGuard, and active development. BungeeCord is in maintenance mode.

Related Guides

• BungeeCord Setup
• BungeeCord IP Forwarding
• BungeeGuard Setup
• Velocity Guide
• Failed to Verify Username
• Common Issues