{"record":{"id":"4c987aea16bf6281","repo":"quarkusio/quarkus","slug":"classnotfoundexception-name","errorCode":null,"errorMessage":"ClassNotFoundException: ${name}","messagePattern":"ClassNotFoundException: (.+?)","errorType":"exception","errorClass":"ClassNotFoundException","httpStatus":null,"severity":"error","filePath":"independent-projects/bootstrap/core/src/main/java/io/quarkus/bootstrap/classloading/QuarkusClassLoader.java","lineNumber":597,"sourceCode":"            l.loadClass(name, this.name);\n        }\n        if (isInJdkPackage(name)) {\n            return getParent().loadClass(name);\n        }\n\n        //even if the thread is interrupted we still want to be able to load classes\n        //if the interrupt bit is set then we clear it and restore it at the end\n        boolean interrupted = Thread.interrupted();\n        try {\n            ClassPathResourceIndex classPathResourceIndex = getClassPathResourceIndex();\n            synchronized (getClassLoadingLock(name)) {\n                Class<?> c = findLoadedClass(name);\n                if (c != null) {\n                    return c;\n                }\n                String resourceName = fromClassNameToResourceName(name);\n                if (classPathResourceIndex.isBanned(resourceName)) {\n                    throw new ClassNotFoundException(name);\n                }\n                boolean parentFirst = parentFirst(resourceName, classPathResourceIndex);\n                if (parentFirst) {\n                    try {\n                        return getParent().loadClass(name);\n                    } catch (ClassNotFoundException ignore) {\n                        log.tracef(\"Class %s not found in parent first load from %s\", name, getParent());\n                    }\n                }\n                ClassPathElement classPathElement = classPathResourceIndex.getFirstClassPathElement(resourceName);\n                if (classPathElement != null) {\n                    final ClassPathResource classPathElementResource = classPathElement.getResource(resourceName);\n                    if (classPathElementResource != null) { //can happen if the class loader was closed\n                        byte[] data = classPathElementResource.getData();\n                        definePackage(name, classPathElement);\n                        Class<?> cl = defineClass(name, data, 0, data.length,\n                                protectionDomains.computeIfAbsent(classPathElement,\n                                        ClassPathElement::getProtectionDomain));","sourceCodeStart":579,"sourceCodeEnd":615,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/independent-projects/bootstrap/core/src/main/java/io/quarkus/bootstrap/classloading/QuarkusClassLoader.java#L579-L615","documentation":"loadClass() throws ClassNotFoundException(name) when a class name is explicitly banned in the classloader's resource index (isBanned). Quarkus uses banned resources to prevent certain classes from ever being loaded by this classloader (e.g. classes intentionally hidden from the application).","triggerScenarios":"Class.forName(...)/loadClass on a class whose resource name is registered as banned in the QuarkusClassLoader's classPathResourceIndex — the lookup is aborted before delegating to parent or classpath.","commonSituations":"Application code referencing classes that Quarkus deliberately blocks in that loader; stale/mismatched deployment vs runtime class sets in dev mode; reflection on internal classes excluded by the platform.","solutions":["Remove or restructure the code that references the banned class — it is intentionally not loadable in this loader","If the class is a legit dependency, ensure the correct artifact/version is on the application classpath so the ban doesn't apply","In dev mode, do a clean restart (not live reload) so the classloader index is rebuilt consistently","Check for duplicate/conflicting versions of the extension providing the class"],"exampleFix":"// before\nClass.forName(\"io.quarkus.deployment.some.InternalClass\"); // banned\n// after\n// use the supported runtime API instead of deployment-internal classes","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    Class<?> c = loader.loadClass(name);\n} catch (ClassNotFoundException e) {\n    // class may be banned or absent — check dependency set, do not retry\n    throw new IllegalStateException(\"Class intentionally blocked or missing: \" + name, e);\n}","preventionTips":["Don't reference deployment-internal classes from application/runtime code","Clean-restart dev mode after changing extension versions so the banned-resource index is consistent","Check dependency versions with mvn dependency:tree"],"tags":["classloading","classpath","classnotfound"],"backgroundTag":"class-not-found","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}