Comprehensive Guide: How To Whitelist Bedrock Players On Geyser Servers
Integrating Bedrock Edition players into a Java-based Minecraft server using Geyser requires a specific approach to user identification because Geyser maps Bedrock users to unique UUIDs that often conflict with standard whitelist files. By configuring the floodgate authentication method and correctly formatting the player usernames within your server properties, you can ensure a secure, permission-controlled environment for cross-platform play.
Pre-Operation Requirements and Server Environment Setup
Before attempting to modify access lists, ensure your server architecture is configured to handle cross-platform identity verification. Geyser functions as a bridge, but the whitelist itself resides on the underlying Java server. If your server is running in offline mode to accommodate the bridge, you must enable floodgate to prevent identity spoofing and ensure that player UUIDs are tracked correctly.
- Essential Tools: A server instance running Geyser-Spigot, Geyser-BungeeCord, or Geyser-Velocity, alongside the Floodgate plugin.
- Prerequisites: Administrative access (OP status or console access) to the host server and familiarity with standard server properties configuration.
- Standards: Ensure that your server.properties file has allow-flight set to true if necessary and that enable-whitelist is explicitly set to true.
- Estimated Duration: 10 to 15 minutes of configuration time, assuming the server has already been deployed.
Executing the Whitelist Process for Bedrock Users
The challenge with whitelisting Bedrock users lies in the prefixing system. When Geyser and Floodgate are active, Bedrock usernames are often passed to the server with a period prefix (e.g., .PlayerName). The server treats this period as a legitimate part of the username, and the whitelist must reflect this exact string to grant access.
Step 1: Verification of Floodgate Authentication
Before adding names to the list, confirm that your server is correctly identifying Bedrock players via Floodgate. If you do not use Floodgate, Geyser will assign players random UUIDs that may change upon reconnection, rendering whitelisting nearly impossible. Check your console logs during a login attempt to verify the exact format the player name is taking. If you see a period before the name, you must include that period in your whitelist command.
Step 2: Utilizing Console Commands for Access Control
The most reliable way to whitelist a player is through the live server console. This bypasses potential character encoding issues in text files. Navigate to your server console and input the command whitelist add followed by the exact name as it appears in the server logs. For example, if the player is identified as .Steve, input whitelist add .Steve. Press Enter to commit the change.
Pro-Tip: If the console rejects the command due to the special character, wrap the username in double quotes, such as whitelist add ".Steve", to ensure the shell parses the period correctly.
Step 3: Modifying the Whitelist.json File Manually
If you prefer managing the list through files, navigate to your root server directory and locate the file named whitelist.json. Open this file using a plain text editor. You will see a list of UUIDs and usernames. To add a Bedrock player, create a new entry following the JSON structure: identify the player's unique identifier and their prefixed username.
Warning: Always stop the server before editing JSON files manually. If the syntax is incorrect—missing a comma or an improperly closed bracket—the server will fail to load the whitelist, effectively locking everyone out until the syntax is corrected.
Step 4: Synchronizing the Geyser Configuration
If you are using a proxy setup like BungeeCord or Velocity, ensure that the Geyser configuration file has the remote address and port correctly mapped to the backend server. If the player still cannot connect, check the Geyser configuration setting auth-type. Ensure this is set to floodgate, as this is the industry standard for maintaining consistent player identity across the bridge.
Bedrock players are stuck in void after about 2 minutes of launching ...
Technical Parameters and Configuration Comparisons
The following table outlines the differences between standard Java player whitelisting and the requirements for Bedrock players via the Geyser bridge.
| Feature | Standard Java User | Geyser Bedrock User |
|---|---|---|
| UUID Format | Mojang Standard (v4) | Floodgate Generated (v3/v4) |
| Prefix Requirement | None | Mandatory (Period Prefix) |
| Identification Method | XUID/UUID Sync | Floodgate/Geyser Bridge |
| Whitelist Entry | Direct Username | Prefixed Username (.Name) |
| Console Command | whitelist add [Name] | whitelist add ".[Name]" |
Common Site Failures and Field Fixes
When implementing a whitelist, operators often encounter issues stemming from character parsing or UUID mismatches. Use these field fixes to resolve connectivity errors.
- Root Cause: The "Disconnected from Server" error occurring even after adding the player.
- Actionable Fix: Verify if you included the period prefix. Most Geyser configurations prepend a character; if you forgot it, the server effectively sees an unauthorized user trying to connect.
- Root Cause: The player is kicked for "You are not whitelisted" despite being on the list.
- Actionable Fix: Ensure the whitelist.json file is saved in UTF-8 encoding. If your text editor injected a Byte Order Mark (BOM) or changed the encoding, the server might fail to parse the username correctly.
- Root Cause: UUIDs resetting upon server restart.
- Actionable Fix: Ensure Floodgate is active and correctly configured. If the server is in "offline" mode without Floodgate, Geyser cannot maintain the link, causing the server to perceive the player as a new identity every time they join.
Frequently Asked Questions
Why must I include a period before the Bedrock username?
Geyser uses the period prefix to distinguish Bedrock players from Java players on the backend. This prevents naming collisions and ensures that the server can differentiate between a native Java player named Steve and a Bedrock player named Steve who is connected through the bridge.
Can I use the in-game /whitelist command?
Yes, you can use the in-game command provided you have administrative privileges. However, remember to use quotes around the name if the console or chat interface attempts to interpret the period as a command separator or special character.
What happens if I move from Offline Mode to Online Mode?
If you change your server to online mode, Geyser players may lose access unless you have fully configured Floodgate to handle identity verification. In most cases, you should keep the server in offline mode and rely on the security provided by Floodgate and the whitelist to manage entry.
Does the whitelist persist through server updates?
Yes, the whitelist.json file is standard for Minecraft servers and will persist through software updates. However, it is considered industry best practice to create a manual backup of this file before performing major version migrations or plugin updates.
Optimize Your Server Access Protocols
Securing your server requires a consistent, repeatable approach to cross-platform identity management. By strictly adhering to the prefixed username requirements and maintaining your JSON syntax, you ensure a frictionless experience for your entire community.
