Geyser and Floodgate setup: config, ports, proxies and account linking

5 min readUpdated Nov 3, 2026

The detailed Geyser and Floodgate plugin setup: every important config.yml option, Bedrock ports and the new transport setting, Velocity/BungeeCord key.pem, account linking, packs and updates.

This is the in-depth version. If you just want Bedrock friends to join a Paper server in five minutes, start with Let Bedrock players join your Java server. Come back here to tune the config, fix port problems, run Geyser on a proxy, or link Java and Bedrock accounts.

Config names below match current Geyser (config file version 11) and Floodgate (version 3). Older Geyser versions call the java: section remote: and have no transport option. Always check the comments in your own config.yml; they describe your exact version.

How the two plugins fit together #

Geyser translates. It listens for Bedrock players and turns their connection into a Java connection.
Floodgate lets those players in without a Java account. Without it, every Bedrock player would need to sign in to a paid Java account.
Both go on the same server (or, on a network, see proxies). Get them only from geysermc.org/download, in the version for your platform: Spigot/Paper, Velocity, BungeeCord or Fabric.

1. Install #

Back up your server (backups).
Upload Geyser-Spigot.jar and floodgate-spigot.jar to plugins.
Restart once. This creates plugins/Geyser-Spigot/config.yml and plugins/floodgate/config.yml (plus Floodgate's key.pem).

2. Ports and transport (the part most guides get wrong) #

Java players connect over TCP on your server's port. Bedrock players connect to Geyser, and newer Geyser builds support two connection methods, chosen with transport:

Option	What it uses
`transport: raknet`	The classic method: UDP on `bedrock.port` only. The config marks it as deprecated, to be removed in the future.
`transport: nethernet`	Bedrock's new method: UDP on `webrtc-port` (0 means the same as `bedrock.port`), plus signaling over TCP on `bedrock.port`.
`transport: both`	Both methods. RakNet and NetherNet each need their own UDP port, so `webrtc-port` must differ from `bedrock.port`.

bedrock:
  address: 0.0.0.0
  port: 19132          # Bedrock players type this port
  webrtc-port: 19133   # NetherNet UDP port (must differ from port when transport is "both")
  transport: both
  clone-remote-port: false

What this means on a hosted server:

Only one port? Use transport: raknet and set port to your Java port number (or set clone-remote-port: true, which copies the Java port on every start). RakNet uses UDP and Java uses TCP, so the same number works.
Using nethernet or both? The TCP signaling on bedrock.port clashes with Java if they share a number, so give Geyser its own port, and with both a third one for webrtc-port. On ESN, use extra ports listed on your server's Network page. If you can't, stay on raknet.
Never change server-port in server.properties; Java must keep the panel's port.
Seeing a bind error after a change? See FAILED TO BIND TO PORT.

Players then add the server on Bedrock with your IP in Server Address and the bedrock.port number in Port.

3. The Geyser options worth changing #

Option	What it does	Suggested
`java.auth-type`	`floodgate` (no Java account needed), `online` (Bedrock players sign in to a Java account) or `offline` (only for offline-mode servers)	`floodgate`
`motd.passthrough-motd`	Shows your Java MOTD to Bedrock players. Set false to use `primary-motd` and `secondary-motd` instead	true
`motd.passthrough-player-counts` / `max-players`	Show the Java player count, or Geyser's own	true
`gameplay.server-name`	Name shown in Bedrock's pause menu	Your server's name
`gameplay.show-coordinates`	Bedrock's built-in coordinates display	Match your rules
`gameplay.command-suggestions`	Sends command lists to Bedrock; turn off if clients freeze on join with many plugins	true
`gameplay.enable-integrated-pack`	Sends a small pack that makes some Java features work better on Bedrock	true
`gameplay.force-resource-packs`	Players must accept your packs to join	true if you use packs

Restart after editing (some options say a restart is required in their comment).

4. Floodgate: names, whitelist and linking #

In plugins/floodgate/config.yml:

username-prefix: "."
replace-spaces: true
player-link:
  enabled: true
  require-link: false
  enable-global-linking: true

username-prefix: Bedrock names get a . in front (.Steve) so they can't clash with Java names. Keep a prefix that isn't a letter or number.
replace-spaces: Bedrock gamertags can contain spaces; this turns them into _ so commands work.
Ops and whitelist: use the prefixed name: op .Steve. For the whitelist, use fwhitelist add Steve (Floodgate's command) because Bedrock players aren't in Mojang's name lookup.
Global linking (on by default): a player who owns both editions can link them once and keep the same inventory and progress on either. They join link.geysermc.org on Java, run /linkaccount to get a code, then join it on Bedrock and enter the code there. It then works on every server with global linking on.
require-link: true only lets in Bedrock players who've linked a Java account. Most public servers leave it off.

5. Velocity and BungeeCord networks #

Put Geyser and Floodgate for your proxy (Velocity or BungeeCord version) on the proxy only. The Bedrock port is opened there.
Put Floodgate (Spigot/Paper version) on every backend server. Don't install Geyser on the backends.
Start everything once, then copy key.pem from the proxy's Floodgate folder to plugins/floodgate/ on every backend, replacing theirs. All Floodgates must share the same key.
In the proxy's Floodgate config.yml, set send-floodgate-data: true.
Restart the proxy and backends.

A wrong or missing key shows Bedrock players the invalid-key message ("Please connect through the official Geyser").

6. Resource packs and skins #

Bedrock can't use Java resource packs. Put Bedrock packs (.mcpack or .zip) in plugins/Geyser-Spigot/packs and restart. Java packs need converting first; the Geyser wiki lists converter tools.
Bedrock skins show to Java players automatically through Floodgate. Custom Bedrock skins can take a moment to appear.

7. Keep Geyser updated #

When Bedrock updates, Bedrock players can't join until Geyser supports the new version: they see Outdated server!. Type geyser version in the console to see whether you're up to date. To update, download the new jars from the official page, replace the old ones in plugins and restart. Update Floodgate at the same time. If the Java side is older than Geyser supports, add ViaVersion.

Troubleshooting #

Problem	Check
"Unable to connect to world"	Bedrock port typed on the client matches `bedrock.port`; you restarted after editing; the port isn't shared with Java while using `nethernet`/`both`
Bind error on start	Two listeners on one port: Java, Geyser's port, `webrtc-port`, or `query.port`
"Outdated server!"	Update Geyser and Floodgate
Bedrock players get kicked with a sign-in message	`auth-type` isn't `floodgate`, or Floodgate isn't installed
"Please connect through the official Geyser"	Proxy setups: copy the proxy's `key.pem` to every backend
Anything else	Run `geyser dump` in the console; it makes a debug link the Geyser community can read

FAQ #

Do I need both Geyser and Floodgate?

Geyser alone works only if every Bedrock player has a Java account to sign in with. Add Floodgate so Bedrock players can join without one.

Can Xbox, PlayStation or Switch players join?

Consoles can't type in a custom server address, so they can't join a private server directly. Phones, tablets and Windows can.

Does Geyser work on a vanilla server?

Not as a plugin. Use Paper or Purpur (plugin version), Fabric (mod version), or run Geyser on a proxy in front of the server.

Running your own Minecraft server? ESN Minecraft servers come with a live console, file manager, backups and schedules. See Minecraft plans · or ask in the ESN Systems Discord.

Still stuck? Use the live chat on the panel or ask in the ESN Systems Discord. Last updated November 3, 2026.