Grasscutters/Grasscutter · error · RuntimeException

Failed to load handbook auth page.

Error message

Failed to load handbook auth page.

What it means

Thrown by Grasscutter's HandbookAuthentication authenticator during construction when it cannot read the bundled resource /html/handbook_auth.html. The class eagerly loads the handbook authentication HTML page into a final field; if the resource is missing or unreadable the constructor aborts with this RuntimeException, meaning the handbook auth flow can never present its page.

Source

Thrown at src/main/java/emu/grasscutter/auth/DefaultAuthenticators.java:382

            client.sendMessage(PacketIds.TokenValidateReq, tokenRequest);

            try {
                return future.get(5, TimeUnit.SECONDS);
            } catch (Exception ignored) {
                return null;
            }
        }
    }

    /** Handles authentication for the web GM Handbook. */
    public static class HandbookAuthentication implements HandbookAuthenticator {
        private final String authPage;

        public HandbookAuthentication() {
            try {
                this.authPage = new String(FileUtils.readResource("/html/handbook_auth.html"));
            } catch (Exception ignored) {
                throw new RuntimeException("Failed to load handbook auth page.");
            }
        }

        @Override
        public void presentPage(AuthenticationRequest request) {
            var ctx = request.getContext();
            if (ctx == null) return;

            // Check to see if an IP authentication can be performed.
            if (Grasscutter.getRunMode() == ServerRunMode.HYBRID) {
                var player = Grasscutter.getGameServer().getPlayerByIpAddress(Utils.address(ctx));
                if (player != null) {
                    // Get the player's session token.
                    var sessionKey = player.getAccount().getSessionKey();
                    // Respond with the handbook auth page.
                    ctx.status(200)
                            .result(
                                    this.authPage

View on GitHub (pinned to f373827a83)

Solutions

1. Restore or re-extract /html/handbook_auth.html (rebuild the jar or run Grasscutter's resource extraction so resources are present).
2. Verify the file exists at src/main/resources/html/handbook_auth.html in the build inputs and that the build copies it into the jar.
3. Check file system permissions on the Grasscutter installation directory so the process can read resources.
4. As a workaround, replace the HandbookAuthentication authenticator with another registered AuthenticationSystem authenticator if the handbook is not needed.

Example fix

// before (no page present)
// java -jar grasscutter.jar  -> RuntimeException: Failed to load handbook auth page.
// after
// cp resources/html/handbook_auth.html <install>/html/handbook_auth.html  (or rebuild jar)
// java -jar grasscutter.jar

var res = getClass().getResource("/html/handbook_auth.html");
if (res == null) throw new IllegalStateException("handbook_auth.html missing from classpath/resources");

static boolean handbookPageAvailable() {
    return HandbookAuthentication.class.getResource("/html/handbook_auth.html") != null;
}

try (var in = FileUtils.readResource("/html/handbook_auth.html")) {
    new HandbookAuthentication();
} catch (RuntimeException | IOException e) {
    LOGGER.error("Handbook auth page unavailable: " + e.getMessage());
    // fall back to a different authenticator or disable the handbook endpoint
}

When it happens

Trigger: Constructing the HandbookAuthentication authenticator when /html/handbook_auth.html does not exist in the resources directory, is not extracted by the resource loader (FileUtils.readResource), or cannot be read (permissions/IO error).

Common situations: Running a partially-built Grasscutter where resources were not copied into the jar; deleting or renaming the html folder in resources; running from a stripped distribution missing the handbook page; read-permission problems on the install directory.

Related errors

• Failed to delete file.
• Failed to create file.
• Failed to write to file.
• Unable to load the primary, fallback, and 'en-US' language f

AI-assisted analysis of Grasscutters/Grasscutter@f373827a83 (2026-09-03). Data as JSON: /api/errors/8a71c3d2171b85fa. Report an issue: GitHub.