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 field is ' + field.name() + ' of class ' + field.declaringClass().name().toString()

What it means

This build-time error is thrown by the Quarkus spring-boot-properties extension when a @ConfigurationProperties class (Spring-style) contains a field that is a List of custom objects (e.g. List<Nested>) but the 'quarkus-config-yaml' extension is not present. The code generator can only emit mapping logic for lists of objects via the YAML config machinery, so without that capability the build fails with a DeploymentException naming the offending field and class.

Source

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

                                    genericType, field.declaringClass().name(), bc, configParam,
                                    (trueBranch, value) -> {
                                        Expr optionalOf = trueBranch.invokeStatic(
                                                MethodDesc.of(Optional.class, "of", Optional.class, Object.class),
                                                value);
                                        createWriteValue(trueBranch, configObject, field, fSetter, fUseFieldAccess,
                                                optionalOf);
                                    },
                                    falseBranch -> {
                                        // set Optional.empty if the value isn't set
                                        Expr optionalEmpty = falseBranch.invokeStatic(
                                                MethodDesc.of(Optional.class, "empty", Optional.class));
                                        createWriteValue(falseBranch, configObject, field, fSetter, fUseFieldAccess,
                                                optionalEmpty);
                                    });
                        }
                    } else if (ConfigurationPropertiesUtil.isListOfObject(fieldType)) {
                        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 field is '"
                                            + field.name() + "' of class '" + field.declaringClass().name().toString());
                        }
                        Expr setterValue = yamlListObjectHandler.handle(new YamlListObjectHandler.FieldMember(field),
                                bc, configParam,
                                getEffectiveConfigName(namingStrategy, field), fullConfigName);
                        createWriteValue(bc, configObject, field, setter, useFieldAccess, setterValue);
                    } else {
                        ConfigurationPropertiesUtil.registerImplicitConverter(fieldType, reflectiveClasses);
                        populateTypicalProperty(bc, configObject, configPropertyBuildItemCandidates,
                                currentClassInHierarchy, field, useFieldAccess, fieldType, setter, configParam,
                                fullConfigName);
                    }
                }
            }

            ConfigPropertyBuildItemCandidateUtil.removePropertiesWithDefaultValue(classLoader,
                    currentClassInHierarchy.name().toString(),

View on GitHub (pinned to e1c734241f)

Solutions

1. Add the quarkus-config-yaml extension: ./mvnw quarkus:add-extension -Dextensions='quarkus-config-yaml' (or add io.quarkus:quarkus-config-yaml to pom.xml).
2. Restructure the property class to avoid List of objects, e.g. use Map<String, Nested> or a yaml-friendly mapping style, or flatten the properties.
3. If the list elements are simple types (String, Integer), keep them — only lists of custom objects are restricted.

Example fix

// before (pom.xml, no yaml extension)
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-spring-boot-properties</artifactId>
</dependency>

// after
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-spring-boot-properties</artifactId>
</dependency>
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-config-yaml</artifactId>
</dependency>

// build-time guard: ensure yaml extension is present when using List-of-object config fields
boolean needsYaml = configClassFields.stream()
    .anyMatch(f -> List.class.isAssignableFrom(f.getType())
        && !isSimpleType(f.getType().getGenericSuperclass()));
if (needsYaml && !dependencies.contains("io.quarkus:quarkus-config-yaml")) {
    throw new IllegalStateException("Add quarkus-config-yaml for List-of-object config fields");
}

When it happens

Trigger: A class annotated with Spring's @ConfigurationProperties has a field of type List<SomePojo> (non-primitive element type) and the application's dependencies do not include quarkus-config-yaml; the error fires during populateConfigObject while generating the config class population bytecode in the deployment phase.

Common situations: Migrating a Spring Boot app with nested list properties (e.g. app.servers[0].host=...) to Quarkus; adding a nested-object list to an existing properties class; a starter/extension set that omits quarkus-config-yaml.

Related errors

• Failed to open path tree with root %s
• Dev services for ${request.getName()} requires a startable s
• Name cannot start with '/':${name}
• The class (${name}) cannot be created during deployment.
• Use GeneratedServiceProviderBuildItem to register service pr

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