How to Install GeyserMC & FloodGate

Downloading Geyser

Download the latest version of Geyser from the Geyser download page.

For Paper, Purpur, Spigot, and compatible Bukkit-based servers, select Spigot and download Geyser-Spigot.jar.

Important: Minecraft Bedrock 26.60 and newer require NetherNet. Update Geyser before following this guide so your installation supports the new connection protocol.

Check Geyser’s supported versions before installing. If your Java server runs an older supported Minecraft version, you may also need ViaVersion so it accepts the Java client version that Geyser uses.

Installing Geyser

1. Stop your server.

2. Upload Geyser-Spigot.jar to your server’s plugins folder using the WitherHosting file manager or SFTP.

3. Start the server once to generate Geyser’s configuration files.

4. Stop the server before editing the configuration.

If you need help uploading the plugin, follow our How to Upload Files guide.

Open Geyser’s configuration file:

plugins/Geyser-Spigot/config.yml

This is the configuration location for the Spigot/Paper version of Geyser.

Updating an existing installation? Back up your configuration and replace the old Geyser JAR with the latest download. Start the server once before reviewing the settings below.

Allocating a Port for NetherNet

NetherNet uses TCP for signaling, which helps Bedrock players find and connect to your server, and UDP for gameplay.

When using Geyser’s built-in signaling, allocate a separate Bedrock port. It cannot share the Java server’s TCP port. The same additional port number can handle both Bedrock TCP and UDP traffic.

To create an additional allocation:

1. Open WitherPanel and select your server.

2. Open Network.

3. Click Create Allocation.

4. Note the address and port assigned to the new allocation.

Keep your existing Java allocation as the primary allocation. You can add a note to the additional allocation to identify it as your Geyser port. See How to create ports for more details.

Important: Your Bedrock allocation must be reachable over both TCP and UDP. If you cannot create an allocation or need help confirming protocol availability, contact WitherHosting support.

The port is the number after the colon in an address such as 203.0.113.10:19132. It is not necessarily five digits.

Configuring NetherNet

In plugins/Geyser-Spigot/config.yml, find the existing bedrock section and update the following settings.

The example uses 19132. Replace this with the additional port assigned to your server.

bedrock:
  address: 0.0.0.0
  port: 19132
  clone-remote-port: false
  transport: nethernet
  webrtc-port: 0
  signaling:
    mode: builtin

These settings follow Geyser’s current configuration format:

• address: 0.0.0.0 allows Geyser to listen on the server’s available network interfaces.

• port sets your allocated Bedrock port.

• clone-remote-port: false keeps Geyser from replacing it with the Java server port.

• transport: nethernet enables NetherNet.

• webrtc-port: 0 makes UDP gameplay use the same port number specified in port.

• mode: builtin makes Geyser handle signaling itself.

Info: These are selected settings, not a complete replacement configuration. Edit the existing sections and preserve the other generated options.

For this Geyser-Spigot installation, leave the Java connection settings at their generated defaults. Configure the authentication mode as explained below.

Authentication Mode

Find auth-type under the java section of Geyser’s configuration:

java:
  auth-type: online

Choose the mode that matches your server:

These options control how Geyser connects Bedrock players to the Java server. Whether Java players must authenticate is controlled by your Java server or proxy configuration.

Floodgate allows Bedrock players to join an online-mode Java server without requiring Java Edition ownership. You do not need to disable Java online mode just to use Floodgate.

If you choose floodgate, complete the next section.

Installing Floodgate

Download Floodgate from the Floodgate download page and select the Spigot/Paper build.

1. Stop your server.

2. Upload the Floodgate JAR to your plugins folder.

3. Start the server once to generate Floodgate’s files, then stop it.

4. Open Geyser’s config.yml.

5. Set the authentication type under java to floodgate:

java:
  auth-type: floodgate

Save your changes. Geyser and Floodgate must both be installed for this authentication mode to work.

Floodgate Configuration

Open the config.yml inside Floodgate’s generated plugin folder.

For a new installation, the default username settings are:

username-prefix: "."
replace-spaces: true

• username-prefix distinguishes Bedrock usernames from Java usernames. Keeping the default . helps prevent name conflicts.

• replace-spaces: true changes spaces in Bedrock usernames to underscores.

For example, an unlinked Bedrock player named John Doe would appear as .John_Doe with these settings.

Secure Profile Configuration

For Paper, Purpur, Spigot, and other compatible servers, open server.properties in your server’s main directory and set:

enforce-secure-profile=false

The setting is enforce-secure-profile, with profile in the singular.

Bedrock does not support Java’s secure-chat system, so this setting is relevant to Geyser connections whether you use Floodgate or another authentication mode. Save the file and restart your server after completing your changes.

Customizing the Server Name and MOTD

In the current Geyser configuration, custom MOTD text belongs in the motd section, while the displayed server name belongs in gameplay.

To use custom Bedrock text, edit the existing sections:

motd:
  primary-motd: "My Minecraft Server"
  secondary-motd: "Java and Bedrock players welcome!"
  passthrough-motd: false

gameplay:
  server-name: "My Minecraft Server"

Set passthrough-motd to true if you want Geyser to display your Java server’s MOTD. The custom MOTD fields apply when passthrough is disabled. These options are documented in Geyser’s current configuration source.

Use setting names to find these options, as line numbers change between releases.

Connecting from Bedrock

After restarting your server, add it in Minecraft Bedrock using:

• Server Name: Any name you want to save.

• Server Address: The public IP address or hostname associated with your Bedrock allocation.

• Port: The additional Bedrock port configured in Geyser.

If your previous Geyser setup used the Java server’s port, update the port in your saved Bedrock server entry.

First-Connection Trust Prompt

Geyser’s built-in signaling uses HTTP unless HTTPS is configured. Bedrock players may therefore see a “Trust on First Use” prompt when joining for the first time.

HTTPS signaling removes this prompt when configured with a valid certificate and matching domain name. Contact WitherHosting support for available HTTPS options, or read Geyser’s HTTPS for NetherNet guide.

Alternative: Using NetherNet with Only the Java Port

If a separate TCP port is unavailable, Geyser can use external signaling. Its default external signaling service is Warden.

For this alternative, update the existing bedrock section:

bedrock:
  address: 0.0.0.0
  clone-remote-port: true
  transport: nethernet
  webrtc-port: 0
  signaling:
    mode: nxs

The Java server’s port must still be available over UDP for Bedrock gameplay.

Restart the server and check the console for the external signaling address and port. Bedrock players must use the connection details shown there, unless you have separately configured a custom domain with the signaling provider.

You can run geyser nethernet in the server console to view external signaling status and diagnostics.

Need Help?

If players cannot connect, check the console for errors and confirm that the required ports are available for your chosen signaling method.

Open a live chat with WitherHosting if you need assistance. Include the relevant console errors and a diagnostic link generated by running:

geyser dump

This gives support information about your Geyser installation and configuration.