What causes "Required class not found" in spring-projects/spring-security?

Add the missing WAS class's jar (WAS_HOME/plugins, com.ibm.ws.runtime.jar or the WAS client jar) to the application classpath.

spring-projects/spring-security · error · RuntimeException

Required class 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.

Solutions

Add the missing WAS class's jar (WAS_HOME/plugins, com.ibm.ws.runtime.jar or the WAS client jar) to the application classpath.
Deploy on/against a genuine WebSphere runtime; the pre-auth websphere package is WAS-specific and will not work on other containers.
Check WAS classloader policy (parent-last/parent-first) so the webapp can load com.ibm.websphere.security classes from the server runtime.
Match the class name in the message against your WAS version; upgrade spring-security-web if the WAS API moved.
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");
}

Defensive patterns

Strategy: validation

Validate before calling

// 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);
    }
}

Type guard

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

Try / catch

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;
}

Prevention

Run the integration only inside a WebSphere container
Check WAS classloader policy so com.ibm.* provider classes are visible to the webapp
Verify required WAS classes with Class.forName checks during deployment smoke tests
Keep WAS runtime jars and spring-security-web versions consistent with your server

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

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

Appendix: 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)