spring-projects/spring-security · error · RuntimeException

Required class<className> not found

Error message

Required class<className> not found

What it means

getMethod resolves a declared method on a WebSphere internal class by loading the class and its parameter types via Class.forName and calling getDeclaredMethod. When a required class (the target class or one of the parameter type names) cannot be found on the classpath, a ClassNotFoundException is caught and rethrown as a RuntimeException with the message "Required class<className> not found". This guards against calling WAS APIs that simply do not exist in the current environment.

Source

Thrown at web/src/main/java/org/springframework/security/web/authentication/preauth/websphere/DefaultWASUsernameAndGroupsExtractor.java:179

					+ Arrays.asList(args) + ")";
			logger.error(message, ex);
			throw new RuntimeException(message, ex);
		}
	}

	private static Method getMethod(String className, String methodName, String[] parameterTypeNames) {
		try {
			Class<?> c = Class.forName(className);
			int len = parameterTypeNames.length;
			Class<?>[] parameterTypes = new Class[len];
			for (int i = 0; i < len; i++) {
				parameterTypes[i] = Class.forName(parameterTypeNames[i]);
			}
			return c.getDeclaredMethod(methodName, parameterTypes);
		}
		catch (ClassNotFoundException ex) {
			logger.error("Required class" + className + " not found");
			throw new RuntimeException("Required class" + className + " not found", ex);
		}
		catch (NoSuchMethodException ex) {
			logger.error("Required method " + methodName + " with parameter types (" + Arrays.asList(parameterTypeNames)
					+ ") not found on class " + className);
			throw new RuntimeException("Required class" + className + " not found", ex);
		}
	}

	private static Method getRunAsSubjectMethod() {
		if (getRunAsSubject == null) {
			getRunAsSubject = getMethod("com.ibm.websphere.security.auth.WSSubject", "getRunAsSubject",
					new String[] {});
		}
		return getRunAsSubject;
	}

	private static Method getGroupsForUserMethod() {
		if (getGroupsForUser == null) {

View on GitHub (pinned to 96852e8860)

Solutions

1. Ensure the application runs on WebSphere/WAS and add the WAS runtime libraries (e.g. com.ibm.ws.runtime.jar, WAS_HOME/plugins) to the classpath.
2. Check the className in the message against your WAS version's javadoc - the internal class may have moved or been renamed in your WAS release.
3. If intentionally running outside WAS, switch to a different authentication mechanism instead of the WebSphere pre-auth module.
4. Use pf (class path) tooling or Class.forName in a test to confirm each com.ibm.websphere.security class resolves before startup.
5. Wrap extractor initialization in a startup check so missing WAS classes fail fast with a clear deployment error.

Example fix

// before
// runtime failure inside getMethod when com.ibm.* classes are missing
// after
try {
    Class.forName("com.ibm.websphere.security.auth.WSSubject");
} catch (ClassNotFoundException e) {
    throw new IllegalStateException(
        "WebSphere runtime classes not on classpath - WASPreAuthenticatedProcessingHandler requires WebSphere/WAS", e);
}

public static void assertWasClassesPresent() {
    String[] required = {
        "com.ibm.websphere.security.auth.WSSubject",
        "com.ibm.websphere.security.cred.WSCredential"
    };
    for (String name : required) {
        try {
            Class.forName(name);
        } catch (ClassNotFoundException e) {
            throw new IllegalStateException("Missing required WAS class: " + name, e);
        }
    }
}
// call at startup before enabling the WAS pre-auth filter

boolean wasClassPresent(String className) {
    try {
        Class.forName(className);
        return true;
    } catch (ClassNotFoundException e) {
        return false;
    }
}

try {
    extractor.getWebSphereGroups(securityName);
} catch (RuntimeException ex) {
    if (ex.getCause() instanceof ClassNotFoundException) {
        throw new IllegalStateException("WAS runtime classes missing from classpath", ex);
    }
    throw ex;
}

When it happens

Trigger: Calling any of getRunAsSubjectMethod, getGroupsForUserMethod, getSecurityNameMethod, or getNarrowMethod when the referenced WAS class (e.g. com.ibm.websphere.security.auth.WSSubject) or one of its parameter type names is not present on the classpath.

Common situations: Deploying the WebSphere pre-auth module on a non-WebSphere server (Tomcat, Jetty) where com.ibm.* classes are absent; missing was_publib / WAS runtime jars on the classpath; a WAS version rename or removal of an internal class; fat-jar packaging that excluded provider jars.

Related errors

• Required class <className> not found
• Error while invoking method <methodClass>.<methodName>(<args
• Couldn't locate: org.springframework.ldap.core.support.BaseL
• invalid item: " + item.getClass()
• Could not locate field 'X' on class Y

AI-assisted analysis of spring-projects/spring-security@96852e8860 (2026-09-10). Data as JSON: /api/errors/9b9084e045e5d3ec. Report an issue: GitHub.