# How to Fix 'Failed to Verify Username' on Your Minecraft Server (/docs/minecraft/fix-failed-verify-username)



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

**"Failed to verify username"** means the server tried to confirm a player's account with Mojang's session servers and didn't get a valid response. It's almost always one of three things: a Mojang outage, an `online-mode` mismatch, or a misconfigured proxy (BungeeCord/Velocity).

Quick Diagnosis [#quick-diagnosis]

| What you see                                    | Most likely cause                      |
| ----------------------------------------------- | -------------------------------------- |
| All players failing at the same time            | Mojang session servers are down        |
| Only one player failing                         | Their client / account / network issue |
| Failing only on a backend server behind a proxy | BungeeCord/Velocity forwarding broken  |
| Failing right after enabling a proxy            | Backend `online-mode` not set to false |

Fix It [#fix-it]

<Steps>
  <Step>
    Check Mojang's status [#check-mojangs-status]

    Visit [status.mojang.com](https://status.mojang.com/) or [xitter.com](https://twitter.com/MojangStatus). If the **Sessions** service is down, **wait** — there's nothing to fix on your end. This usually clears in 5–30 minutes.
  </Step>

  <Step>
    Verify online-mode for your setup [#verify-online-mode-for-your-setup]

    Open `server.properties` and check `online-mode`:

    | Setup                                           | online-mode |
    | ----------------------------------------------- | ----------- |
    | Standalone server (no proxy)                    | `true`      |
    | Backend server behind BungeeCord/Velocity proxy | `false`     |
    | Standalone "cracked" server (insecure)          | `false`     |

    If you have a **proxy**, the proxy handles authentication and the backend must have `online-mode=false`. Otherwise both the proxy *and* the backend will try to authenticate, and the second one fails.
  </Step>

  <Step>
    Check BungeeCord/Velocity IP forwarding [#check-bungeecordvelocity-ip-forwarding]

    Behind a proxy, the backend needs to **trust the proxy's player info**. This requires:

    * **BungeeCord legacy mode**: `settings.yml` → `ip_forward: true` and Spigot's `bungeecord: true`
    * **Modern Velocity / Paper**: Velocity secret key in Paper's `paper-global.yml` → `proxies.velocity.secret`

    Without forwarding, the backend rejects connections from the proxy. See [BungeeCord IP Forwarding](/docs/minecraft/bungeecord-ip-forwarding).
  </Step>

  <Step>
    For single-player issues, try client-side fixes [#for-single-player-issues-try-client-side-fixes]

    If only one player can't connect:

    1. **Restart their Minecraft launcher** (not just the game)
    2. **Sign out and back into their Microsoft/Mojang account** in the launcher
    3. **Try a different Minecraft profile** to rule out a corrupted profile
    4. **Check their internet** — failed handshakes can come from packet loss
    5. **Switch DNS to 1.1.1.1 or 8.8.8.8** to rule out their ISP DNS
  </Step>
</Steps>

How online-mode Works [#how-online-mode-works]

| Setting             | What happens at login                                                           |
| ------------------- | ------------------------------------------------------------------------------- |
| `online-mode=true`  | Server contacts `sessionserver.mojang.com` to verify the player owns their UUID |
| `online-mode=false` | Server skips verification — accepts any username                                |

> **Security warning:** `online-mode=false` allows cracked clients but **also lets anyone connect with any username**, including impersonating your admins. Only disable on private servers behind a whitelist or proxy.

Proxy Authentication Flow [#proxy-authentication-flow]

When you have a BungeeCord/Velocity proxy:

```
Player → Proxy (online-mode=true, authenticates with Mojang)
         ↓
         Backend (online-mode=false, trusts proxy via IP forwarding)
```

If forwarding is broken, the backend doesn't trust the proxy and rejects the connection. Symptoms:

* "Failed to verify username" on the backend
* "If you wish to use IP forwarding, please enable it..." in proxy console
* Backend log shows player connecting with random UUID

Common Mistakes [#common-mistakes]

| Mistake                                              | Fix                                                                  |
| ---------------------------------------------------- | -------------------------------------------------------------------- |
| Backend `online-mode=true` behind a proxy            | Set to `false` on the backend                                        |
| Proxy `online-mode=false`                            | Set to `true` on the proxy (Mojang verification happens here)        |
| Forgetting to enable BungeeCord mode in `spigot.yml` | Set `bungeecord: true`                                               |
| Velocity secret missing or mismatched                | Copy the exact secret from `forwarding.secret` to `paper-global.yml` |
| Restarting only the backend after config change      | Restart **both** proxy and backend                                   |

Related Guides [#related-guides]

* [BungeeCord Setup](/docs/minecraft/bungeecord-guide)
* [BungeeCord IP Forwarding](/docs/minecraft/bungeecord-ip-forwarding)
* [BungeeCord Troubleshooting](/docs/minecraft/bungeecord-troubleshooting)
* [Server Properties](/docs/minecraft/server-properties)
* [Common Issues](/docs/minecraft/common-issues)