{"record":{"id":"131709993377068c","repo":"quarkusio/quarkus","slug":"unable-to-load-class-classname-for-supporting","errorCode":null,"errorMessage":"Unable to load class '{className}' for supporting custom JSON serialization","messagePattern":"Unable to load class '(.+?)' for supporting custom JSON serialization","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"extensions/resteasy-reactive/rest-jackson/runtime/src/main/java/io/quarkus/resteasy/reactive/jackson/runtime/ResteasyReactiveServerJacksonRecorder.java","lineNumber":135,"sourceCode":"        return (Class<? extends BiFunction<ObjectMapper, Type, ObjectWriter>>) customSerializationMap.get(clazz.getName());\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    public static Class<? extends BiFunction<ObjectMapper, Type, ObjectReader>> customDeserializationForMethod(\n            String methodId) {\n        return (Class<? extends BiFunction<ObjectMapper, Type, ObjectReader>>) customDeserializationMap.get(methodId);\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    public static Class<? extends BiFunction<ObjectMapper, Type, ObjectReader>> customDeserializationForClass(Class<?> clazz) {\n        return (Class<? extends BiFunction<ObjectMapper, Type, ObjectReader>>) customDeserializationMap.get(clazz.getName());\n    }\n\n    private Class<?> loadClass(String className) {\n        try {\n            return Thread.currentThread().getContextClassLoader().loadClass(className);\n        } catch (ClassNotFoundException e) {\n            throw new RuntimeException(\"Unable to load class '\" + className + \"' for supporting custom JSON serialization\", e);\n        }\n    }\n}\n","sourceCodeStart":117,"sourceCodeEnd":139,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/resteasy-reactive/rest-jackson/runtime/src/main/java/io/quarkus/resteasy/reactive/jackson/runtime/ResteasyReactiveServerJacksonRecorder.java#L117-L139","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Add the dependency containing the named class to the runtime classpath (fix its Maven scope to compile/runtime, not provided)","Verify the fully-qualified class name referenced by @JsonView/@CustomSerialization/@CustomDeserialization still exists (rebuild after refactors)","Run ./mvnw clean install to clear stale build output referencing removed classes","For native images, ensure the class is registered for reflection and not excluded by native configuration"],"exampleFix":"<!-- before -->\n<dependency>\n  <groupId>com.acme</groupId><artifactId>api-models</artifactId><scope>provided</scope>\n</dependency>\n\n<!-- after -->\n<dependency>\n  <groupId>com.acme</groupId><artifactId>api-models</artifactId>\n</dependency>","handlingStrategy":"validation","validationCode":"String cn = \"com.acme.Views.Public\";\ntry {\n    Class.forName(cn, false, Thread.currentThread().getContextClassLoader());\n} catch (ClassNotFoundException e) {\n    throw new IllegalStateException(\"Class \" + cn + \" referenced by @JsonView/@CustomSerialization is not on the runtime classpath\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    startApplication();\n} catch (RuntimeException e) {\n    if (e.getCause() instanceof ClassNotFoundException\n            && e.getMessage() != null && e.getMessage().contains(\"Unable to load class\")) {\n        // add the missing dependency or fix the referenced class name\n    }\n}","preventionTips":["Keep @JsonView/@CustomSerialization/@CustomDeserialization classes in compile-scope artifacts","Clean-build after refactors that rename or move referenced classes","Verify runtime classpath with mvn dependency:tree for the model jar","For native builds, register referenced classes for reflection"],"tags":["quarkus","jackson","classpath","classloading"],"backgroundTag":"classnotfound-runtime","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"}