quarkusio/quarkus · error · RuntimeException

io.undertow.server.session.SecureRandomSessionIdGenerator mu

Error message

io.undertow.server.session.SecureRandomSessionIdGenerator must be exactly 64 characters long

What it means

A static initializer in UndertowDeploymentRecorder configures the session-id alphabet via the system property io.undertow.server.session.SecureRandomSessionIdGenerator.ALPHABET. Undertow requires this alphabet to contain exactly 64 distinct characters; Quarkus enforces it and throws a RuntimeException at build/start time otherwise.

Source

Thrown at extensions/undertow/runtime/src/main/java/io/quarkus/undertow/runtime/UndertowDeploymentRecorder.java:830

    /**
     * we can't have SecureRandom in the native image heap, so we need to lazy init
     */
    private static class QuarkusSessionIdGenerator implements SessionIdGenerator {

        private volatile SecureRandom random;

        private volatile int length = 30;

        private static final char[] SESSION_ID_ALPHABET;

        private static final String ALPHABET_PROPERTY = "io.undertow.server.session.SecureRandomSessionIdGenerator.ALPHABET";

        static {
            String alphabet = System.getProperty(ALPHABET_PROPERTY,
                    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_");
            if (alphabet.length() != 64) {
                throw new RuntimeException(
                        "io.undertow.server.session.SecureRandomSessionIdGenerator must be exactly 64 characters long");
            }
            SESSION_ID_ALPHABET = alphabet.toCharArray();
        }

        @Override
        public String createSessionId() {
            if (random == null) {
                random = new SecureRandom();
            }
            final byte[] bytes = new byte[length];
            random.nextBytes(bytes);
            return new String(encode(bytes));
        }

        public int getLength() {
            return length;
        }

View on GitHub (pinned to e1c734241f)

Solutions

1. Set the property to exactly 64 characters, or remove the -D flag to use the default alphabet
2. Count the characters programmatically before setting it
3. Avoid characters outside [A-Za-z0-9-_] unless you also account for URL-safety

Example fix

// before
java -Dio.undertow.server.session.SecureRandomSessionIdGenerator.ALPHABET=ABC... (not 64 chars) app.jar
// after
java -Dio.undertow.server.session.SecureRandomSessionIdGenerator.ALPHABET=ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_ app.jar

String a = System.getProperty("io.undertow.server.session.SecureRandomSessionIdGenerator.ALPHABET");
if (a != null && a.length() != 64) throw new IllegalArgumentException("ALPHABET must be exactly 64 chars, got " + a.length());

When it happens

Trigger: The JVM is started with -Dio.undertow.server.session.SecureRandomSessionIdGenerator.ALPHABET set to a string whose length is not exactly 64.

Common situations: Copy-pasted system property with a truncated or extended alphabet; security hardening scripts that add/remove characters; typo when overriding the default.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Top-level project base directory <dir> specified with system
• Cannot create bean
• Unable to get listed resource ${i} from directory ${path} fo
• Cannot serve directory
• A generic type is not allowed here; try creating a subclass

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/8535f5bb293846e7. Report an issue: GitHub.