What causes "Transformed username is null." in apereo/cas?

Review the configured principalNameTransformer and test it against the actual submitted username format.

apereo/cas · error · AccountNotFoundException

Transformed username is null.

Error message

Transformed username is null.

What it means

transformUsername throws AccountNotFoundException when the configured principalNameTransformer transforms the credential id into a blank string. The raw id was present, but after applying the transformation (regex strip, truncation, script, etc.) nothing remained, so the account is treated as not found.

Solutions

Review the configured principalNameTransformer and test it against the actual submitted username format.
Fix the transformer pattern/script so it returns a non-empty value, or add a fallback return of the original id.
Remove the transformer if no transformation is needed (default transformer returns the input).
Log the raw and transformed values to pinpoint the mismatch.
Validate username format upstream (form validation) so only matching values reach the transformer.

Example fix

// before (Groovy transformer script)
def run(Object[] args) { return args[0].toString().replaceAll('^.*\\\\\\\|', '') } // strips everything when no backslash
// after
def run(Object[] args) { def u = args[0].toString(); def i = u.indexOf('\\\\'); return i >= 0 ? u.substring(i + 1) : u }

Defensive patterns

Strategy: validation

Validate before calling

// preflight the transformer against real username formats
String out = principalNameTransformer.transform("jdoe@example.org");
if (StringUtils.isBlank(out)) { throw new IllegalStateException("Transformer returns blank for valid usernames"); }

Try / catch

try {
    return handler.authenticate(credential, service);
} catch (AccountNotFoundException e) {
    if (e.getMessage() != null && e.getMessage().contains("Transformed username")) {
        LOGGER.error("Principal name transformer produced empty value; check regex/script", e);
    }
    throw e;
}

Prevention

Unit test the principal name transformer with all username formats in use (uid, email, DOMAIN\\user).
Prefer transformers that return the original value when the pattern doesn't match.
Log raw vs transformed values when debugging transformer issues.

When it happens

Trigger: Calling transformUsername with a valid non-blank credential id whose principalNameTransformer.transform(...) returns null or empty — e.g. a regex/ groovy transformer whose pattern fails to match, or one configured to cut the id to zero length.

Common situations: Principal name transformer regex that doesn't match the actual username format (e.g. domain-stripping pattern against plain usernames); misconfigured Groovy/JS transformer script returning null; transformer configured for one handler family but the credential format differs (email vs uid).

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

AI-assisted analysis of apereo/cas@e7288fc434 (2026-09-08). Data as JSON: /api/errors/7eaf02c62f79f916. Report an issue: GitHub.

Appendix: source

Thrown at core/cas-server-core-authentication-api/src/main/java/org/apereo/cas/authentication/handler/support/AbstractPreAndPostProcessingAuthenticationHandler.java:73

                                                                       @Nullable final Principal principal,
                                                                       @Nullable final List<MessageDescriptor> warnings) {
        return new DefaultAuthenticationHandlerExecutionResult(this, credential, principal, warnings);
    }

    protected AuthenticationHandlerExecutionResult createHandlerResult(final Credential credential,
                                                                       final Principal principal) {
        return new DefaultAuthenticationHandlerExecutionResult(this, credential,
            principal, new ArrayList<>());
    }

    protected String transformUsername(final Credential credential) throws Throwable {
        if (StringUtils.isBlank(credential.getId())) {
            throw new AccountNotFoundException("Username is null.");
        }
        LOGGER.debug("Transforming credential username via [{}]", principalNameTransformer.getClass().getName());
        val transformedUsername = principalNameTransformer.transform(credential.getId());
        if (StringUtils.isBlank(transformedUsername)) {
            throw new AccountNotFoundException("Transformed username is null.");
        }
        if (credential instanceof final MutableCredential mc) {
            mc.setId(transformedUsername);
        }
        return transformedUsername;
    }
}

View on GitHub (pinned to e7288fc434)