apereo/cas · error · AccountNotFoundException

not found in backing file.

Error message

 not found in backing file.

What it means

FileAuthenticationHandler authenticates users against a plaintext file of username:password entries. It throws AccountNotFoundException with '<username> not found in backing file.' when getPasswordOnRecord(username) returns blank, i.e. no entry (or an empty password field) exists for that user in the configured file.

Solutions

  1. Verify the username exists as a line in the configured file (check exact spelling and case after any transformation)
  2. Confirm the entry has a non-empty password field in the expected format (username:password)
  3. Check cas.authn.accept.users / file resource config points to the current file and it is readable
  4. If users are transient, switch to a handler backed by a database/LDAP instead of a static file

Example fix

// before (backing file)
jdoe:
// after
jdoe:{plain}password123
Defensive patterns

Strategy: validation

Validate before calling

// before authentication, ensure the user entry exists in the file
boolean known = Files.lines(Path.of(fileName))
    .anyMatch(line -> line.startsWith(username + ":") && line.length() > username.length() + 1);

Try / catch

try {
    return handler.authenticate(credential);
} catch (AccountNotFoundException e) {
    // treat as unknown user; return generic invalid-credentials response
}

Prevention

When it happens

Trigger: authenticateUsernamePasswordInternal called with a credential whose transformed username has no matching line in this.fileName, or whose file entry has a blank password.

Common situations: Typo in username at login; user missing from the password file; file format deviation (wrong separator) so parsing yields a blank password; pointing at a stale/partial copy of the backing file; comment/whitespace lines confusing parsers.

Understand the failure class

Background: "User not found", "Invalid user", and "does not exist": what missing-user lookup errors mean across Rocket.Chat, LiteLLM, Phabricator, rustfs, and pnpm — this error's family across 10 libraries.

Related errors

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

Appendix: source

Thrown at support/cas-server-support-generic/src/main/java/org/apereo/cas/adaptors/generic/FileAuthenticationHandler.java:61

    public FileAuthenticationHandler(final String name,
                                     final PrincipalFactory principalFactory,
                                     final Resource fileName, final String separator) {
        super(name, principalFactory, null);
        this.fileName = fileName;
        this.separator = separator;
    }

    @Override
    protected AuthenticationHandlerExecutionResult authenticateUsernamePasswordInternal(final UsernamePasswordCredential transformedCredential,
                                                                                        final String originalPassword) throws Throwable {
        try {
            if (this.fileName == null) {
                throw new FileNotFoundException("Filename does not exist");
            }
            val username = transformedCredential.getUsername();
            val passwordOnRecord = getPasswordOnRecord(username);
            if (StringUtils.isBlank(passwordOnRecord)) {
                throw new AccountNotFoundException(username + " not found in backing file.");
            }
            if (matches(originalPassword, passwordOnRecord)) {
                val principal = this.principalFactory.createPrincipal(username);
                return createHandlerResult(transformedCredential, principal, new ArrayList<>());
            }
        } catch (final IOException e) {
            throw new PreventedException(e);
        }
        throw new FailedLoginException();
    }

    /**
     * Gets the password on record.
     *
     * @param username the username
     * @return the password on record
     * @throws IOException Signals that an I/O exception has occurred.
     */

View on GitHub (pinned to e7288fc434)