Pumpkin-MC/Pumpkin · error · BungeeCordError

Invalid BungeeGuard token

Error message

Invalid BungeeGuard token

What it means

BungeeCordError raised when the forwarded data contains a BungeeGuard token that does not match the configured shared secret, meaning the connection did not pass through the trusted proxy with the correct token.

Solutions

1. Reject the connection
2. Ensure proxy and backend share the same BungeeGuard token
3. Log the failed token check at warn level

When it happens

Trigger: Thrown at crates/pumpkin/src/net/proxy/bungeecord.rs:27 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of Pumpkin-MC/Pumpkin@8d4639e25a (2026-09-09). Data as JSON: /api/errors/b8e172f268d00cf8. Report an issue: GitHub.

Appendix: source

Thrown at crates/pumpkin/src/net/proxy/bungeecord.rs:27

use pumpkin_protocol::Property;

/// The property name the `BungeeGuard` plugin uses to forward its shared
/// secret inside the profile properties.
const BUNGEEGUARD_TOKEN_PROPERTY: &str = "bungeeguard-token";

#[derive(Error, Debug)]
pub enum BungeeCordError {
    #[error("Failed to parse address")]
    FailedParseAddress,
    #[error("Failed to parse UUID")]
    FailedParseUUID,
    #[error("Failed to parse properties")]
    FailedParseProperties,
    #[error("Failed to make offline UUID")]
    FailedMakeOfflineUUID,
    #[error("No BungeeGuard token in forwarded data")]
    MissingToken,
    #[error("Invalid BungeeGuard token")]
    InvalidToken,
}

/// Attempts to login a player via `BungeeCord`.
///
/// This function should be called when receiving the `SLoginStart` packet.
/// It utilizes the `server_address` received in the `SHandShake` packet,
/// which may contain optional data about the client:
///
/// 1. IP address (if `ip_forward` is enabled on the `BungeeCord` server)
/// 2. UUID (if `ip_forward` is enabled on the `BungeeCord` server)
/// 3. Game profile properties (if `ip_forward` and `online_mode` are enabled on the `BungeeCord` server)
///
/// If a `secret` is configured, the properties must contain a property named
/// `bungeeguard-token` holding the secret, as injected by the `BungeeGuard`
/// plugin. The token property is stripped from the profile, and a missing or
/// mismatched token rejects the connection. This also blocks players
/// connecting directly to this server, bypassing the proxy.

View on GitHub (pinned to 8d4639e25a)