quarkusio/quarkus · error · RuntimeException

Unable to load class '{className}' for supporting custom JSO

Error message

Unable to load class '{className}' for supporting custom JSON serialization

What it means

At static-init time, the RESTEasy Reactive Jackson recorder records JSON views and custom (de)serializers by loading the named classes through the runtime classloader. If a class name recorded during the build cannot be loaded at runtime, the recorder wraps the ClassNotFoundException in a RuntimeException and fails startup. This typically means the class existed at build time but is absent (or not visible to the TCCL) at runtime — e.g. it lives in a dependency that is not on the runtime classpath.

Source

Thrown at extensions/resteasy-reactive/rest-jackson/runtime/src/main/java/io/quarkus/resteasy/reactive/jackson/runtime/ResteasyReactiveServerJacksonRecorder.java:135

        return (Class<? extends BiFunction<ObjectMapper, Type, ObjectWriter>>) customSerializationMap.get(clazz.getName());
    }

    @SuppressWarnings("unchecked")
    public static Class<? extends BiFunction<ObjectMapper, Type, ObjectReader>> customDeserializationForMethod(
            String methodId) {
        return (Class<? extends BiFunction<ObjectMapper, Type, ObjectReader>>) customDeserializationMap.get(methodId);
    }

    @SuppressWarnings("unchecked")
    public static Class<? extends BiFunction<ObjectMapper, Type, ObjectReader>> customDeserializationForClass(Class<?> clazz) {
        return (Class<? extends BiFunction<ObjectMapper, Type, ObjectReader>>) customDeserializationMap.get(clazz.getName());
    }

    private Class<?> loadClass(String className) {
        try {
            return Thread.currentThread().getContextClassLoader().loadClass(className);
        } catch (ClassNotFoundException e) {
            throw new RuntimeException("Unable to load class '" + className + "' for supporting custom JSON serialization", e);
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Add the dependency containing the named class to the runtime classpath (fix its Maven scope to compile/runtime, not provided)
2. Verify the fully-qualified class name referenced by @JsonView/@CustomSerialization/@CustomDeserialization still exists (rebuild after refactors)
3. Run ./mvnw clean install to clear stale build output referencing removed classes
4. For native images, ensure the class is registered for reflection and not excluded by native configuration

Example fix

<!-- before -->
<dependency>
  <groupId>com.acme</groupId><artifactId>api-models</artifactId><scope>provided</scope>
</dependency>

<!-- after -->
<dependency>
  <groupId>com.acme</groupId><artifactId>api-models</artifactId>
</dependency>

String cn = "com.acme.Views.Public";
try {
    Class.forName(cn, false, Thread.currentThread().getContextClassLoader());
} catch (ClassNotFoundException e) {
    throw new IllegalStateException("Class " + cn + " referenced by @JsonView/@CustomSerialization is not on the runtime classpath");
}

try {
    startApplication();
} catch (RuntimeException e) {
    if (e.getCause() instanceof ClassNotFoundException
            && e.getMessage() != null && e.getMessage().contains("Unable to load class")) {
        // add the missing dependency or fix the referenced class name
    }
}

When it happens

Trigger: Referencing a @JsonView / @CustomSerialization / @CustomDeserialization class that is only available at compile time (provided-scope or generated/removed dependency), or a class in a module excluded from the runtime artifact (e.g. native-image excluded or wrong artifact).

Common situations: Wrong Maven scope (compile-only) for the jar holding the view/serializer class; renaming/refactoring a class without rebuilding; GraalVM native builds where the class is not reachable for reflection; classloader visibility issues in multi-module setups.

Related errors

• The class (${name}) cannot be created during deployment.
• Unable to load repository/entity class mapping ->
• Failed to load CodeGenProvider class from deployment classlo
• Failed to read %s
• Failed to read resources from classpath

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