quarkusio/quarkus · error · IllegalArgumentException

Can't load class: <settingStringValue>

Error message

Can't load class: <settingStringValue>

What it means

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.

Source

Thrown at extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/boot/FastBootMetadataBuilder.java:693

    private <T> T loadSettingInstance(String settingName, Object settingValue, Class<T> clazz) {
        T instance = null;
        Class<? extends T> instanceClass = null;

        if (clazz.isAssignableFrom(settingValue.getClass())) {
            instance = (T) settingValue;
        } else if (settingValue instanceof Class) {
            instanceClass = (Class<? extends T>) settingValue;
        } else if (settingValue instanceof String) {
            String settingStringValue = (String) settingValue;
            if (standardServiceRegistry != null) {
                final ClassLoaderService classLoaderService = standardServiceRegistry.getService(ClassLoaderService.class);

                instanceClass = classLoaderService.classForName(settingStringValue);
            } else {
                try {
                    instanceClass = (Class<? extends T>) Class.forName(settingStringValue);
                } catch (ClassNotFoundException e) {
                    throw new IllegalArgumentException("Can't load class: " + settingStringValue, e);
                }
            }
        } else {
            throw new IllegalArgumentException(
                    "The provided " + settingName + " setting value [" + settingValue + "] is not supported!");
        }

        if (instanceClass != null) {
            try {
                instance = instanceClass.getConstructor().newInstance();
            } catch (InstantiationException | IllegalAccessException | NoSuchMethodException | InvocationTargetException e) {
                throw new IllegalArgumentException(
                        "The " + clazz.getSimpleName() + " class [" + instanceClass + "] could not be instantiated!",
                        e);
            }
        }

        return instance;

View on GitHub (pinned to e1c734241f)

Solutions

1. Fix the fully-qualified class name in the configuration property.
2. Add the module/dependency containing the class to the application.
3. 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.
4. Check 'Caused by: ClassNotFoundException' to see exactly which name failed to resolve.

Example fix

// before
quarkus.hibernate.orm.metadata-builder-contributor=com.example.MyMetadaContributor // typo
// after
quarkus.hibernate.orm.metadata-builder-contributor=com.example.MyMetadataContributor

// Verify the class resolves before booting the PU
try {
    Class.forName("com.example.MyMetadataContributor");
} catch (ClassNotFoundException e) {
    throw new IllegalStateException("Contributor class not on classpath", e);
}

try {
    bootPersistenceUnit();
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Can't load class")) {
        log.error("Check the FQCN configured for the contributor/strategy setting", e.getCause());
    }
}

When it happens

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

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

Related errors

• The Hibernate ORM configuration in Quarkus does not support
• Could not find provider class: " + name
• RuntimeException(e)
• RuntimeException(e)
• Datasource must be defined for persistence unit '%s'. Settin

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