# How to Set Up a Whitelist on Your Minecraft Server (/docs/minecraft/whitelist-setup)



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

A whitelist restricts your server to **only approved players**. Anyone not on the list is rejected at connection. This is the strongest access control — stronger than a password, since usernames are tied to verified Mojang accounts.

Enable the Whitelist [#enable-the-whitelist]

<Tabs items={['Via Console (Recommended)', 'Via server.properties']}>
  <Tab value="Via Console (Recommended)">
    <Steps>
      <Step>
        Open the Console [#open-the-console]

        In the [XGamingServer Panel](https://panel.xgamingserver.com), click **Console** in the sidebar.
      </Step>

      <Step>
        Enable the whitelist [#enable-the-whitelist-1]

        ```
        whitelist on
        ```

        The whitelist is now active. Any non-whitelisted player who tries to join will be rejected with "You are not whitelisted on this server!"
      </Step>

      <Step>
        (Optional) Kick non-whitelisted players who are already online [#optional-kick-non-whitelisted-players-who-are-already-online]

        ```
        whitelist enforce
        ```

        This is the equivalent of `enforce-whitelist=true` and immediately kicks any connected player who isn't on the list.
      </Step>
    </Steps>
  </Tab>

  <Tab value="Via server.properties">
    <Steps>
      <Step>
        Stop the server [#stop-the-server]
      </Step>

      <Step>
        Open server.properties [#open-serverproperties]

        Click **Files** in the sidebar and open `server.properties`.
      </Step>

      <Step>
        Set the flags [#set-the-flags]

        ```
        white-list=true
        enforce-whitelist=true
        ```

        `enforce-whitelist=true` kicks non-whitelisted players who are already online when the whitelist is enabled. Set it to `false` if you want to leave existing players alone and only block new connections.
      </Step>

      <Step>
        Save and start [#save-and-start]
      </Step>
    </Steps>
  </Tab>
</Tabs>

Manage the Whitelist [#manage-the-whitelist]

All commands work in the panel **Console** or in-game (with OP):

| Command                         | Description                                |
| ------------------------------- | ------------------------------------------ |
| `whitelist add <PlayerName>`    | Add a player to the whitelist              |
| `whitelist remove <PlayerName>` | Remove a player from the whitelist         |
| `whitelist list`                | Show all whitelisted players               |
| `whitelist on`                  | Enable the whitelist                       |
| `whitelist off`                 | Disable the whitelist (anyone can join)    |
| `whitelist reload`              | Reload `whitelist.json` after manual edits |

> **Tip:** Use the player's **exact username** including capitalization. The whitelist is **NOT** case-sensitive in modern Minecraft versions, but quoting it correctly avoids confusion.

Edit whitelist.json Directly [#edit-whitelistjson-directly]

The whitelist is stored in `whitelist.json` in the server root. Each entry has the player's UUID and name:

```json
[
  {
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "name": "Notch"
  },
  {
    "uuid": "853c80ef-3c37-49fd-aa49-938b674adae6",
    "name": "jeb_"
  }
]
```

Find UUIDs at [mcuuid.net](https://mcuuid.net) by entering the username.

After editing the file directly, run `whitelist reload` in the **Console** to apply changes without restarting.

OPs Bypass the Whitelist [#ops-bypass-the-whitelist]

Server operators (players in `ops.json`) can **always join** regardless of whitelist status. This means:

* You don't need to add yourself to the whitelist if you're already an OP
* New OPs are automatically allowed
* Use this combo for staff-only servers: enable whitelist, OP your staff, no one else can join

Common Issues [#common-issues]

| Problem                 | Fix                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------ |
| Player not found        | The username doesn't exist in Mojang's database. Check spelling — modern Minecraft uses Mojang verification  |
| Whitelist not enforcing | Run `whitelist reload` after manual `whitelist.json` edits                                                   |
| OP can't join           | OPs bypass the whitelist by default. If they still can't join, check `enforce-whitelist` and the server logs |
| Online-mode false       | If `online-mode=false`, the whitelist verifies by username only — players can spoof names                    |

Related Guides [#related-guides]

* [OP Permissions](/docs/minecraft/op-permissions)
* [Server Properties](/docs/minecraft/server-properties)
* [Ban & Unban Players](/docs/minecraft/ban-unban-players)