quarkusio/quarkus · error · RuntimeException

Unable to register password for user:${user} make sure it is

Error message

Unable to register password for user:${user} make sure it is a valid hex encoded ${algorithm} hash

What it means

When a properties-file realm user password is stored as a hex-encoded hash, the recorder attempts to reconstruct the password with the configured WildFly Elytron PasswordFactory algorithm. If the stored value is not a valid hex string for that algorithm (or the algorithm name is wrong), it wraps the failure in this RuntimeException.

Source

Thrown at extensions/elytron-security-properties-file/runtime/src/main/java/io/quarkus/elytron/security/properties/runtime/ElytronPropertiesFileRecorder.java:157

                log.debugf("RoleInfoMap: %s%n", roleInfo);
                for (Map.Entry<String, String> userPasswordEntry : userInfo.entrySet()) {
                    Password password;
                    String user = userPasswordEntry.getKey();

                    if (runtimeConfig.plainText()) {
                        password = ClearPassword.createRaw(ClearPassword.ALGORITHM_CLEAR,
                                userPasswordEntry.getValue().toCharArray());
                    } else {
                        try {
                            byte[] hashed = ByteIterator.ofBytes(userPasswordEntry.getValue().getBytes(StandardCharsets.UTF_8))
                                    .asUtf8String().hexDecode().drain();

                            password = PasswordFactory
                                    .getInstance(runtimeConfig.algorithm().getName(),
                                            new WildFlyElytronPasswordProvider())
                                    .generatePassword(new DigestPasswordSpec(user, config.realmName(), hashed));
                        } catch (Exception e) {
                            throw new RuntimeException("Unable to register password for user:" + user
                                    + " make sure it is a valid hex encoded "
                                    + runtimeConfig.algorithm().getName().toUpperCase() + " hash", e);
                        }
                    }

                    PasswordCredential passwordCred = new PasswordCredential(password);
                    List<Credential> credentials = new ArrayList<>();
                    credentials.add(passwordCred);
                    String rawRoles = roleInfo.get(user);
                    String[] roles = rawRoles != null ? rawRoles.split(",") : new String[0];
                    Attributes attributes = new MapAttributes();
                    for (String role : roles) {
                        attributes.addLast("groups", role);
                    }
                    SimpleRealmEntry entry = new SimpleRealmEntry(credentials, attributes);
                    identityMap.put(user, entry);
                    log.debugf("Added user(%s), roles=%s%n", user, attributes.get("groups"));
                }

View on GitHub (pinned to e1c734241f)

Solutions

1. Re-generate the hash for the configured algorithm (e.g. with Elytron's tooling) and paste the exact hex output
2. Confirm the configured algorithm name matches the hash format (e.g. simple-digest-md5 vs digest-*)
3. Ensure the password line format is correct: user=<hex-hash> without whitespace/BOM
4. Verify the realm name used to compute the hash matches the configured realm name

Example fix

// before (users.properties)
admin=zz91 NotHex
// after
admin=5f4dcc3b5aa765d61d8327deb882cf99

try {
    Hex.decodeHex(storedHash.toCharArray());
} catch (IllegalArgumentException e) {
    throw new IllegalStateException("user password is not valid hex for configured algorithm");
}

try {
    realm.registerUser(user, hash);
} catch (RuntimeException e) {
    throw new IllegalStateException("Invalid password hash for " + user + ": regenerate with the configured algorithm", e);
}

When it happens

Trigger: A user entry in users.properties contains a password value that fails PasswordFactory.generatePassword — e.g. not valid hex, wrong digest length for the configured algorithm, or mismatched realm-name in the DigestPasswordSpec.

Common situations: Hand-edited hashed passwords with typos; hash generated for a different algorithm than quarkus.elytron.security.properties-file.plain-or-encrypted/algorithm config; wrong realm name so the digest doesn't validate; uppercase/lowercase or whitespace issues in hex.

Related errors

• No PropertiesRealmConfig users/roles settings found. Configu
• No producers for required item %s, step builder used: %s
• cycle detection failure report (dynamic CycleBuildException
• Build step '%s' does not produce any build item and thus wil
• Cannot consume/produce interface or abstract class build ite

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