quarkusio/quarkus · error · IllegalStateException

Unable to load the config property type: ${className}

Error message

Unable to load the config property type: ${className}

What it means

MicroProfileConfigRecorder.load converts a config property type name into a Class via Class.forName; when the type cannot be resolved it throws this IllegalStateException naming the type. This happens during build-time registration/validation of @ConfigProperties. The ClassNotFoundException is chained for diagnosis.

Source

Thrown at extensions/arc/runtime/src/main/java/io/quarkus/arc/runtime/MicroProfileConfigRecorder.java:119

            case "short":
                return short.class;
            case "int":
                return int.class;
            case "long":
                return long.class;
            case "float":
                return float.class;
            case "double":
                return double.class;
            case "char":
                return char.class;
            case "void":
                return void.class;
            default:
                try {
                    return Class.forName(className, true, cl);
                } catch (ClassNotFoundException e) {
                    throw new IllegalStateException("Unable to load the config property type: " + className, e);
                }
        }
    }

    public static class ConfigValidationMetadata {
        private final String name;
        private final String rawTypeName;
        private final List<String> actualTypeArgumentNames;
        private final String defaultValue;

        @RecordableConstructor
        public ConfigValidationMetadata(final String name, final String rawTypeName, final List<String> actualTypeArgumentNames,
                final String defaultValue) {
            this.name = name;
            this.rawTypeName = rawTypeName;
            this.actualTypeArgumentNames = actualTypeArgumentNames;
            this.defaultValue = defaultValue;
        }

View on GitHub (pinned to e1c734241f)

Solutions

1. Ensure the type referenced by the config property is on the application/deployment classpath and spelled correctly
2. Clean rebuild the application so stale generated metadata referencing renamed types is refreshed
3. If the type is a primitive or array, confirm the recorder input uses the expected JVM name form
4. Check that the ConfigValidationMetadata was produced in the same build as the config class

Example fix

// before
@ConfigProperties(prefix = "app")
public class MyAppConfig {
    public SomeMissingType value; // class not on build classpath
}
// after
import com.example.SomeType;
@ConfigProperties(prefix = "app")
public class MyAppConfig {
    public SomeType value;
}

for (String typeName : referencedConfigTypes) {
    try { Class.forName(typeName, false, cl); }
    catch (ClassNotFoundException e) {
        throw new IllegalStateException("Config property type not on build classpath: " + typeName, e);
    }
}

try {
    recorder.registerConfigProperties(...);
} catch (IllegalStateException e) {
    logger.error("Fix or remove the unresolvable config property type", e);
}

When it happens

Trigger: A @ConfigProperties class (or validateConfigProperties/registerConfigProperties input) references a property type whose class name is not visible to the recorder's classloader — e.g. a primitive-mapped name typo or a class not on the deployment classpath.

Common situations: Referencing a type from an extension module missing at build time; typos in generated/derived class names; classloader split issues between deployment and runtime modules; renaming a config class without a clean rebuild.

Related errors

• The class (${name}) cannot be created during deployment.
• The supplied 'main-class' value of '${mainClassName}' does n
• Either @ConfigRoot or @ConfigMapping is missing on ${configR
• Unable to load the datasource driver <driverName> for the <f
• Injected class not found in index:

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