How to Fix Floodgate Skin and Authentication Issues

Common Floodgate Problems

Floodgate is the companion plugin for Geyser that lets Bedrock players join Java servers without owning a Java account. It works well once configured, but the initial setup has several points where things can go wrong. Skin rendering, authentication and username handling are the top three areas where you will need to fix floodgate skin issues or auth errors.

This guide assumes you already have Geyser and Floodgate installed. If not, follow our crossplay setup guide first.

Bedrock Skins Not Showing

The most common complaint is that Bedrock players appear as Steve or Alex to Java players. This happens because Bedrock skins are sent as raw texture data, while Java Edition expects skins to come from Mojang's skin servers. Floodgate bridges this gap by uploading Bedrock skins to a third-party skin server (typically Mineskin), but several things can prevent that from working.

Check Floodgate Config

Open plugins/floodgate/config.yml and verify these values:

send-floodgate-data: true
skin-upload:
  enabled: true

If skin-upload is disabled, Bedrock skins will not be sent to Java clients at all. Enable it and restart.

Mineskin Rate Limits

Floodgate uses Mineskin to convert Bedrock skin data into a Java-compatible format. Mineskin has rate limits, and if many Bedrock players join at once (e.g., during a server launch), skin uploads queue up and some players may appear skinless for minutes. You can fix floodgate skin issues caused by rate limits by:

• Waiting. Skins usually resolve within 1 to 3 minutes as the queue clears.
• Adding a Mineskin API key in the Floodgate config to get higher rate limits.
• Having players relog after a minute if their skin did not load on first join.

Custom Skins vs Marketplace Skins

Floodgate can upload standard custom skins that Bedrock players create using the in-game skin editor. Marketplace skins (purchased DLC) use a different format that Floodgate cannot always convert. Players using marketplace skins may appear as Steve/Alex. The workaround is to ask those players to switch to a custom skin for servers, or accept that marketplace skins will not display on Java clients.

See crossplay in action: Astroworld MC, IP play.astroworldmc.com, Java + Bedrock.

Authentication Failures

If Bedrock players see "Disconnected" or "Unable to connect to world" immediately after joining, the issue is almost always a key mismatch between Geyser and Floodgate.

Key Mismatch

Geyser and Floodgate communicate using a shared key.pem file. In plugin mode, this is handled automatically. In standalone mode, you must copy the key.pem from your Geyser standalone data folder to the Floodgate plugin folder on the Java server. If these files differ, authentication fails silently.

# On the Geyser standalone machine:
cat /path/to/geyser/key.pem

# Copy this file to the Java server:
scp /path/to/geyser/key.pem user@javaserver:/plugins/floodgate/key.pem

Restart both Geyser and the Java server after replacing the key.

Online Mode Conflicts

If your Java server has online-mode=true in server.properties, it expects all players to have valid Java accounts. Floodgate bypasses this for Bedrock players, but only if Floodgate loads before the server checks authentication. On Paper and Spigot, this usually works out of the box. On Velocity or BungeeCord, make sure Floodgate is installed on the proxy, not just the backend, and that player forwarding is configured correctly.

Username Prefix Issues

Floodgate adds a prefix (default: .) to Bedrock usernames to avoid name collisions with Java players. A Bedrock player named "Steve" becomes ".Steve" on the server. This can cause issues with plugins that do not handle the prefix correctly.

Changing the Prefix

In config.yml:

username-prefix: "."

You can change this to any character, but keep it short. Some admins use * or +. If you remove the prefix entirely (empty string), you risk name collisions where a Java player and a Bedrock player share the same name, which can corrupt player data.

Plugins That Break with Prefixes

Permission plugins, economy plugins and whitelist plugins sometimes reject usernames starting with a dot. If a Bedrock player cannot use commands or has wrong permissions, check whether the plugin stores data by username and whether it handles the prefix. LuckPerms works fine with prefixed names. Older plugins may need manual config entries using the prefixed name.

Host any Bedrock or crossplay server with zero config headaches. Astroworld Hosting supports Geyser, BDS, and every server type on every plan.

Skin Geometry Errors

Bedrock supports custom skin geometry (non-standard player models) that Java Edition does not. If a Bedrock player uses a skin with custom geometry (wider arms, extra limbs, taller body), Floodgate strips the geometry and uploads only the base texture. The result may look distorted on Java clients. To fix floodgate skin issues related to geometry, ask the player to use a standard Steve or Alex model skin.

Network Setups (Velocity/BungeeCord)

On proxy-based networks, install Floodgate on the proxy and on every backend server. The proxy handles initial authentication, and backend servers need Floodgate to recognize Bedrock players when they switch servers. If Floodgate is only on the proxy, backend servers may treat Bedrock players as unauthenticated and kick them.

Make sure all Floodgate instances across your network share the same key.pem. Differing keys between proxy and backend servers cause intermittent authentication failures.

Debugging Checklist

• Verify key.pem is identical on Geyser and all Floodgate instances.
• Check that skin-upload: enabled: true is set.
• Confirm UDP 19132 is open for Geyser.
• Look at server console logs for Floodgate errors on player join.
• Test with a default (non-marketplace) skin.
• Ensure Floodgate is on the proxy in network setups.

For more on Geyser deployment options that affect Floodgate behavior, see our Geyser standalone vs plugin comparison.