quarkusio/quarkus · error · DeploymentException

Support for List of objects in classes annotated with '@Conf

Error message

Support for List of objects in classes annotated with '@ConfigProperties' is only possible via the 'quarkus-config-yaml' extension. Offending method is ' + method.name() + ' of interface ' + method.declaringClass().name().toString()

What it means

When a @ConfigProperties interface method returns List<SomeObject>, the generated config mapping requires special YAML list-object support which only the quarkus-config-yaml extension provides. If that capability is absent at build time, deployment aborts with a DeploymentException.

Source

Thrown at extensions/spring-boot-properties/deployment/src/main/java/io/quarkus/spring/boot/properties/deployment/InterfaceConfigurationPropertiesUtil.java:250

                                    // convert the String value and populate an Optional with it
                                    ConfigurationPropertiesUtil.createReadOptionalValueAndConvertIfNeeded(
                                            fullConfigName,
                                            genericType, method.declaringClass().name(), bc, config,
                                            (trueBranch, value) -> {
                                                // return Optional.of() using the converted value
                                                trueBranch.return_(trueBranch.invokeStatic(
                                                        MethodDesc.of(Optional.class, "of", Optional.class, Object.class),
                                                        value));
                                            },
                                            falseBranch -> {
                                                // return Optional.empty() if no config value was read
                                                falseBranch.return_(falseBranch.invokeStatic(
                                                        MethodDesc.of(Optional.class, "empty", Optional.class)));
                                            });
                                }
                            } else if (ConfigurationPropertiesUtil.isListOfObject(method.returnType())) {
                                if (!capabilities.isPresent(Capability.CONFIG_YAML)) {
                                    throw new DeploymentException(
                                            "Support for List of objects in classes annotated with '@ConfigProperties' is only possible via the 'quarkus-config-yaml' extension. Offending method is '"
                                                    + method.name() + "' of interface '"
                                                    + method.declaringClass().name().toString());
                                }
                                Expr value = yamlListObjectHandler.handle(
                                        new YamlListObjectHandler.MethodReturnTypeMember(method), bc, config,
                                        nameAndDefaultValue.getName(), fullConfigName);
                                bc.return_(value);
                            } else {
                                if (defaultValueStr != null) {
                                    /*
                                     * The effect this will have is to add a ConfigSource with a lower priority
                                     * This ensures that when we try to read the property value using
                                     * config.getValue(fullConfigName), the default value will be returned if none is
                                     * set
                                     */
                                    defaultConfigValues
                                            .produce(new RunTimeConfigurationDefaultBuildItem(fullConfigName,

View on GitHub (pinned to e1c734241f)

Solutions

Add io.quarkus:quarkus-config-yaml to the application dependencies
Restructure config to use a nested class exposing indexed properties instead of List<SomeClass>
Convert the list configuration to use YAML with the yaml extension installed

Example fix

// pom.xml before
<dependency>io.quarkus:quarkus-spring-boot-properties</dependency>
// after
<dependency>io.quarkus:quarkus-spring-boot-properties</dependency>
<dependency>io.quarkus:quarkus-config-yaml</dependency>

Defensive patterns

Strategy: validation

Validate before calling

boolean needsYamlExtension(Class<?> cfg) {
    for (Method m : cfg.getMethods()) {
        Type gt = m.getGenericReturnType();
        if (gt instanceof ParameterizedType p && p.getRawType() == List.class
            && ((Class<?>) p.getActualTypeArguments()[0]).isInterface() == false
            && !p.getActualTypeArguments()[0].getTypeName().startsWith("java.")) return true;
    }
    return false;
}

Try / catch

catch (DeploymentException e) { if (e.getMessage().contains("quarkus-config-yaml")) { /* add quarkus-config-yaml dependency */ } throw e; }

Prevention

Add quarkus-config-yaml whenever config uses nested object lists
Keep list-of-object config in YAML files, not .properties
Check dependencies before migrating Spring Boot list config

When it happens

Trigger: Interface annotated with @ConfigProperties has a method whose return type is List<SomeClass> (list of objects, not scalars) and the application does not include the quarkus-config-yaml dependency.

Common situations: Spring Boot migration with nested list-of-object configuration (e.g. List<ServerConfig>) relying on .properties/.yml via the default SmallRye converter, which cannot express nested object lists.

Related errors

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