spring-projects/spring-security · error · RuntimeException

Required class <className> not found

Error message

Required class <className> not found

What it means

The private getClass helper loads a WebSphere credential/API class by name via Class.forName. If the class is not on the classpath, the ClassNotFoundException is rethrown as a RuntimeException "Required class <className> not found". Callers like getWSCredentialClass and authenticationPrincipal rely on this to access WAS credential types, so it fails whenever WAS runtime classes are absent.

Source

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

		}
		return narrow;
	}

	// SEC-803
	private static Class<?> getWSCredentialClass() {
		if (wsCredentialClass == null) {
			wsCredentialClass = getClass("com.ibm.websphere.security.cred.WSCredential");
		}
		return wsCredentialClass;
	}

	private static Class<?> getClass(String className) {
		try {
			return Class.forName(className);
		}
		catch (ClassNotFoundException ex) {
			logger.error("Required class " + className + " not found");
			throw new RuntimeException("Required class " + className + " not found", ex);
		}
	}

}

View on GitHub (pinned to 96852e8860)

Solutions

1. Add the missing WAS class's jar (WAS_HOME/plugins, com.ibm.ws.runtime.jar or the WAS client jar) to the application classpath.
2. Deploy on/against a genuine WebSphere runtime; the pre-auth websphere package is WAS-specific and will not work on other containers.
3. Check WAS classloader policy (parent-last/parent-first) so the webapp can load com.ibm.websphere.security classes from the server runtime.
4. Match the class name in the message against your WAS version; upgrade spring-security-web if the WAS API moved.
5. Fail fast at startup by verifying required com.ibm.* classes are loadable before enabling the WAS pre-auth filter.

Example fix

// before
Class<?> credentialClass = extractor.getWSCredentialClass(); // throws at runtime if absent
// after
boolean wasPresent;
try {
    Class.forName("com.ibm.websphere.security.cred.WSCredential");
    wasPresent = true;
} catch (ClassNotFoundException e) {
    wasPresent = false;
}
if (!wasPresent) {
    throw new IllegalStateException("WSCredential class missing - deploy on WebSphere or add WAS runtime jars");
}

// gate the WAS pre-auth integration on credential class availability at startup
static {
    try {
        Class.forName("com.ibm.websphere.security.cred.WSCredential");
    } catch (ClassNotFoundException e) {
        throw new IllegalStateException(
            "com.ibm.websphere.security.cred.WSCredential not found: deploy on WebSphere or add WAS runtime jars", e);
    }
}

boolean credentialClassAvailable() {
    try {
        Class.forName("com.ibm.websphere.security.cred.WSCredential");
        return true;
    } catch (ClassNotFoundException e) {
        return false;
    }
}

try {
    WSCredential cred = extractor.getCredentials(subject);
} catch (RuntimeException ex) {
    if (ex.getCause() instanceof ClassNotFoundException) {
        throw new IllegalStateException("WSCredential class not on classpath", ex);
    }
    throw ex;
}

When it happens

Trigger: Any call path through logger, log, credentials, getWSCredentialClass, authenticationPrincipal, or spel that needs a WAS class (e.g. com.ibm.websphere.security.cred.WSCredential) when that class cannot be loaded.

Common situations: Running the WebSphere pre-auth integration outside WebSphere (Tomcat/Embedded); WAS client/runtime jars not shipped with the deployment; classloader isolation in WAS preventing the webapp from seeing provider classes; refactoring that renamed the expected WAS class.

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/21940bb34a9d38d1. Report an issue: GitHub.