quarkusio/quarkus · error · ClassNotFoundException

ClassNotFoundException: ${name}

Error message

ClassNotFoundException: ${name}

What it means

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).

Source

Thrown at independent-projects/bootstrap/core/src/main/java/io/quarkus/bootstrap/classloading/QuarkusClassLoader.java:597

            l.loadClass(name, this.name);
        }
        if (isInJdkPackage(name)) {
            return getParent().loadClass(name);
        }

        //even if the thread is interrupted we still want to be able to load classes
        //if the interrupt bit is set then we clear it and restore it at the end
        boolean interrupted = Thread.interrupted();
        try {
            ClassPathResourceIndex classPathResourceIndex = getClassPathResourceIndex();
            synchronized (getClassLoadingLock(name)) {
                Class<?> c = findLoadedClass(name);
                if (c != null) {
                    return c;
                }
                String resourceName = fromClassNameToResourceName(name);
                if (classPathResourceIndex.isBanned(resourceName)) {
                    throw new ClassNotFoundException(name);
                }
                boolean parentFirst = parentFirst(resourceName, classPathResourceIndex);
                if (parentFirst) {
                    try {
                        return getParent().loadClass(name);
                    } catch (ClassNotFoundException ignore) {
                        log.tracef("Class %s not found in parent first load from %s", name, getParent());
                    }
                }
                ClassPathElement classPathElement = classPathResourceIndex.getFirstClassPathElement(resourceName);
                if (classPathElement != null) {
                    final ClassPathResource classPathElementResource = classPathElement.getResource(resourceName);
                    if (classPathElementResource != null) { //can happen if the class loader was closed
                        byte[] data = classPathElementResource.getData();
                        definePackage(name, classPathElement);
                        Class<?> cl = defineClass(name, data, 0, data.length,
                                protectionDomains.computeIfAbsent(classPathElement,
                                        ClassPathElement::getProtectionDomain));

View on GitHub (pinned to e1c734241f)

Solutions

1. Remove or restructure the code that references the banned class — it is intentionally not loadable in this loader
2. If the class is a legit dependency, ensure the correct artifact/version is on the application classpath so the ban doesn't apply
3. In dev mode, do a clean restart (not live reload) so the classloader index is rebuilt consistently
4. Check for duplicate/conflicting versions of the extension providing the class

Example fix

// before
Class.forName("io.quarkus.deployment.some.InternalClass"); // banned
// after
// use the supported runtime API instead of deployment-internal classes

try {
    Class<?> c = loader.loadClass(name);
} catch (ClassNotFoundException e) {
    // class may be banned or absent — check dependency set, do not retry
    throw new IllegalStateException("Class intentionally blocked or missing: " + name, e);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Failed to load the condition class ${testClassName} for capa
• The class (${name}) cannot be created during deployment.
• Can't load class: <settingStringValue>
• Unable to load repository/entity class mapping ->
• Cannot load task class: {taskClass}

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/4c987aea16bf6281. Report an issue: GitHub.