# How to Troubleshoot Common BungeeCord Problems on Your Minecraft Network (/docs/minecraft/bungeecord-troubleshooting)



import { Step, Steps } from 'fumadocs-ui/components/steps';

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 [#quick-triage]

| Symptom                                                    | Most likely cause                                | Section           |
| ---------------------------------------------------------- | ------------------------------------------------ | ----------------- |
| Players land on proxy but can't reach any backend          | Backend offline or wrong address in `config.yml` | Connection Issues |
| Backend crashes with "If you wish to use IP forwarding..." | `ip_forward: true` missing on proxy              | Connection Issues |
| Players get "Failed to verify username"                    | `online-mode` mismatch                           | Authentication    |
| Anyone can join as anyone                                  | BungeeGuard not installed                        | Authentication    |
| Chat doesn't sync between servers                          | No cross-server chat plugin                      | Plugin Issues     |
| `/server` command does nothing                             | Server name typo or restricted                   | Connection Issues |

Connection Issues [#connection-issues]

"Could not connect to a default or fallback server" [#could-not-connect-to-a-default-or-fallback-server]

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

**Fix:**

<Steps>
  <Step>
    Check the backend address [#check-the-backend-address]

    In the [XGamingServer Panel](https://panel.xgamingserver.com), open the **backend** server's **Network** tab. Note the exact IP and port.
  </Step>

  <Step>
    Edit proxy config.yml [#edit-proxy-configyml]

    In the proxy's **Files**, open `config.yml` and verify the `servers` block matches:

    ```yaml
    servers:
      lobby:
        address: 123.45.67.89:25566
        motd: "Lobby"
        restricted: false
    ```
  </Step>

  <Step>
    Confirm the backend is running [#confirm-the-backend-is-running]

    The backend Dashboard must show **Online** with `Done` in the Console.
  </Step>

  <Step>
    Restart the proxy [#restart-the-proxy]
  </Step>
</Steps>

"If you wish to use IP forwarding, please enable it in your BungeeCord config" [#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](/docs/minecraft/bungeecord-ip-forwarding).

Players can't switch with /server <name> [#players-cant-switch-with-server-name]

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

**Fix:**

```yaml
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 [#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 [#authentication-issues]

"Failed to verify username" [#failed-to-verify-username]

`online-mode` is configured incorrectly.

**Fix:**

| Server                                 | Required setting    |
| -------------------------------------- | ------------------- |
| **Proxy** (`config.yml`)               | `online_mode: true` |
| **All backends** (`server.properties`) | `online-mode=false` |

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

Anyone can join as any username [#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](/docs/minecraft/setup-bungeguard)** 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 [#plugin-issues]

Plugins don't work across servers [#plugins-dont-work-across-servers]

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

| Plugin type              | Goes in                   | Examples                                |
| ------------------------ | ------------------------- | --------------------------------------- |
| **BungeeCord plugin**    | Proxy `plugins/` folder   | BungeeChat, BungeeTeleport, RedisBungee |
| **Bukkit/Spigot plugin** | Backend `plugins/` folder | EssentialsX, WorldEdit, LuckPerms       |

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 [#cross-server-chat-doesnt-sync]

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

| Plugin          | Notes                          |
| --------------- | ------------------------------ |
| **BungeeChat**  | Most popular cross-server chat |
| **LunaChat**    | Multi-language support         |
| **VentureChat** | Heavy customization            |

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

Permissions don't sync between backends [#permissions-dont-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](/docs/minecraft/setup-luckperms) and [Use MySQL Database](/docs/minecraft/use-mysql-database).

Performance Issues [#performance-issues]

Proxy uses too much RAM [#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 [#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 [#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 [#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](/docs/minecraft/velocity-guide) has built-in modern forwarding, better error messages, no need for BungeeGuard, and active development. BungeeCord is in maintenance mode.

Related Guides [#related-guides]

* [BungeeCord Setup](/docs/minecraft/bungeecord-guide)
* [BungeeCord IP Forwarding](/docs/minecraft/bungeecord-ip-forwarding)
* [BungeeGuard Setup](/docs/minecraft/setup-bungeguard)
* [Velocity Guide](/docs/minecraft/velocity-guide)
* [Failed to Verify Username](/docs/minecraft/fix-failed-verify-username)
* [Common Issues](/docs/minecraft/common-issues)