{"record":{"id":"ffa4c58ef0fa3021","repo":"quarkusio/quarkus","slug":"can-t-load-class-settingstringvalue","errorCode":null,"errorMessage":"Can't load class: <settingStringValue>","messagePattern":"Can't load class: <settingStringValue>","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/boot/FastBootMetadataBuilder.java","lineNumber":693,"sourceCode":"    private <T> T loadSettingInstance(String settingName, Object settingValue, Class<T> clazz) {\n        T instance = null;\n        Class<? extends T> instanceClass = null;\n\n        if (clazz.isAssignableFrom(settingValue.getClass())) {\n            instance = (T) settingValue;\n        } else if (settingValue instanceof Class) {\n            instanceClass = (Class<? extends T>) settingValue;\n        } else if (settingValue instanceof String) {\n            String settingStringValue = (String) settingValue;\n            if (standardServiceRegistry != null) {\n                final ClassLoaderService classLoaderService = standardServiceRegistry.getService(ClassLoaderService.class);\n\n                instanceClass = classLoaderService.classForName(settingStringValue);\n            } else {\n                try {\n                    instanceClass = (Class<? extends T>) Class.forName(settingStringValue);\n                } catch (ClassNotFoundException e) {\n                    throw new IllegalArgumentException(\"Can't load class: \" + settingStringValue, e);\n                }\n            }\n        } else {\n            throw new IllegalArgumentException(\n                    \"The provided \" + settingName + \" setting value [\" + settingValue + \"] is not supported!\");\n        }\n\n        if (instanceClass != null) {\n            try {\n                instance = instanceClass.getConstructor().newInstance();\n            } catch (InstantiationException | IllegalAccessException | NoSuchMethodException | InvocationTargetException e) {\n                throw new IllegalArgumentException(\n                        \"The \" + clazz.getSimpleName() + \" class [\" + instanceClass + \"] could not be instantiated!\",\n                        e);\n            }\n        }\n\n        return instance;","sourceCodeStart":675,"sourceCodeEnd":711,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/boot/FastBootMetadataBuilder.java#L675-L711","documentation":"When a Hibernate setting expects a class instance (e.g. a MetadataBuilderContributor or PhysicalNamingStrategy) given as a string, FastBootMetadataBuilder.loadSettingInstance converts the string to a Class. If the class loader (Hibernate's ClassLoaderService, or fallback Class.forName) cannot find the named class, it throws this IllegalArgumentException wrapping the ClassNotFoundException.","triggerScenarios":"Setting properties like quarkus.hibernate.orm.metadata-builder-contributor or naming strategies to a class name that is misspelled, not on the classpath, or lives in a module not visible to the runtime classloader at static-init time.","commonSituations":"Typo in fully-qualified class name; contributor class packaged in a dependency missing from the app; using an application class in a Quarkus build where it isn't indexed; renaming/removing a class in a version upgrade while old config remains.","solutions":["Fix the fully-qualified class name in the configuration property.","Add the module/dependency containing the class to the application.","For Quarkus, prefer the typed quarkus.hibernate.orm.metadata-builder-contributor=<FQCN> with the class indexed, or use a build-time bean reference instead of a string setting.","Check 'Caused by: ClassNotFoundException' to see exactly which name failed to resolve."],"exampleFix":"// before\nquarkus.hibernate.orm.metadata-builder-contributor=com.example.MyMetadaContributor // typo\n// after\nquarkus.hibernate.orm.metadata-builder-contributor=com.example.MyMetadataContributor","handlingStrategy":"validation","validationCode":"// Verify the class resolves before booting the PU\ntry {\n    Class.forName(\"com.example.MyMetadataContributor\");\n} catch (ClassNotFoundException e) {\n    throw new IllegalStateException(\"Contributor class not on classpath\", e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    bootPersistenceUnit();\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().startsWith(\"Can't load class\")) {\n        log.error(\"Check the FQCN configured for the contributor/strategy setting\", e.getCause());\n    }\n}","preventionTips":["Copy-paste FQCNs instead of typing them","Keep contributor classes in application dependencies that are indexed by Quarkus","After renames, grep config for old class names","Read the ClassNotFoundException cause for the exact failing name"],"tags":["hibernate-orm","classpath","classnotfound","configuration"],"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"}