Pumpkin-MC/Pumpkin · error · LoginError

The validated username is invalid

Error message

The validated username is invalid

What it means

This is the LoginError::InvalidUsername variant. After successfully validating the JWT chain, Pumpkin extracts the gamertag/username from the authenticated token and rejects it if it does not pass the server's username validity checks. It is thrown so that clients with malformed, empty, or disallowed names never enter the world state.

Solutions

1. Have the player ensure their Xbox Live gamertag is a normal, non-empty name and re-login
2. If testing with a custom client, send a username that satisfies the vanilla name rules (length and allowed characters)
3. Check the server's username validation config/pattern if it has been customized too strictly
4. Update the server if the username rules changed in a newer version

Example fix

// before (custom client payload)
let token = build_login_jwt(""); // empty username
// after
let token = build_login_jwt("ValidName123"); // conforms to name rules

// Caller-side name check before sending a login packet
fn is_valid_username(name: &str) -> bool {
    !name.is_empty()
        && name.len() <= 16
        && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')
}

fn is_invalid_username(e: &LoginError) -> bool {
    matches!(e, LoginError::InvalidUsername)
}

match login_result {
    Err(LoginError::InvalidUsername) => disconnect_with("Your gamertag is not allowed; please change it on Xbox Live"),
    Err(e) => disconnect_with(&format!("Login failed: {e}")),
    Ok(p) => admit(p),
}

When it happens

Trigger: The username decoded from the validated Bedrock login token is empty, exceeds length limits, contains characters outside the allowed set, or otherwise fails the game's name rules (e.g. same rules as Java edition names).

Common situations: Modified clients that send a blank or spoofed gamertag, accounts with unusual characters in their Xbox gamertag, or third-party tools crafting login packets for testing.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• JWT chain validation failed
• Could not parse UUID from validated token
• Cannot accept self-signed token. Authentication is enforced…
• Got a guest/splitscreen login request. Currently…
• Vine response data too short (minimum 89 bytes)

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

Appendix: source

Thrown at crates/pumpkin/src/net/bedrock/login/mod.rs:36

    client::{resource_pack_stack::PackInstanceId, resource_packs_info::PackInfoData},
    server::{login::ClientData, resource_pack_client_response::SResourcePackClientResponse},
};
use pumpkin_util::version::BedrockMinecraftVersion;
use pumpkin_world::{CURRENT_BEDROCK_MC_PROTOCOL, CURRENT_BEDROCK_MC_VERSION};
use serde::{Deserialize, de::Error};
use serde_repr::Deserialize_repr;
use std::sync::Arc;
use thiserror::Error;
use tracing::debug;
use uuid::Uuid;

#[derive(Debug, Error)]
pub enum LoginError {
    #[error("Login packet data is not valid JSON")]
    InvalidTokenFormat(#[from] serde_json::Error),
    #[error("JWT chain validation failed: {0}")]
    ChainValidationFailed(#[from] AuthError),
    #[error("The validated username is invalid")]
    InvalidUsername,
    #[error("Could not parse UUID from validated token")]
    InvalidUuid,
    #[error("Cannot accept self-signed token. Authentication is enforced by server config.")]
    SelfSignedNotAllowed,
    #[error("Got a guest/splitscreen login request. Currently unimplemented.")]
    GuestUnimplemented,
    #[error("Failed to decode extra using decode_b64_url_nopad.")]
    DecodeExtraError,
}

#[derive(Deserialize_repr)]
#[repr(u8)]
enum AuthenticationType {
    Full,
    Guest,
    SelfSigned,
}

View on GitHub (pinned to 8d4639e25a)