quarkusio/quarkus · error · IllegalArgumentException

Value must be an instance of List<> for ResteasyClientBuilde

Error message

Value must be an instance of List<> for ResteasyClientBuilder setter method: ${builderMethodName}

What it means

When a resteasy.* property maps to a ResteasyClientBuilder method that takes more than one parameter, the library requires the value to be a List so it can be spread into the method arguments. This error is thrown when a multi-argument builder method is invoked but the supplied value is not a List. It is a configuration/usage type mismatch detected at builder time.

Source

Thrown at extensions/resteasy-classic/resteasy-client/runtime/src/main/java/io/quarkus/restclient/runtime/QuarkusRestClientBuilder.java:673

    @Override
    public RestClientBuilder property(String name, Object value) {
        if (name.startsWith(RESTEASY_PROPERTY_PREFIX)) {
            // Makes it possible to configure some of the ResteasyClientBuilder delegate properties
            String builderMethodName = name.substring(RESTEASY_PROPERTY_PREFIX.length());
            Method builderMethod = Arrays.stream(ResteasyClientBuilder.class.getMethods())
                    .filter(m -> builderMethodName.equals(m.getName()) && m.getParameterCount() >= 1)
                    .findFirst()
                    .orElse(null);
            if (builderMethod == null) {
                throw new IllegalArgumentException("ResteasyClientBuilder setter method not found: " + builderMethodName);
            }
            Object[] arguments;
            if (builderMethod.getParameterCount() > 1) {
                if (value instanceof List) {
                    arguments = ((List<?>) value).toArray();
                } else {
                    throw new IllegalArgumentException(
                            "Value must be an instance of List<> for ResteasyClientBuilder setter method: "
                                    + builderMethodName);
                }
            } else {
                arguments = new Object[] { value };
            }
            try {
                builderMethod.invoke(builderDelegate, arguments);
            } catch (IllegalAccessException | IllegalArgumentException | InvocationTargetException e) {
                throw new IllegalStateException("Unable to invoke ResteasyClientBuilder method: " + builderMethodName, e);
            }
        }
        builderDelegate.property(name, value);
        return this;
    }

    private Object newInstanceOf(Class<?> clazz) {
        if (PROVIDER_FACTORY != null) {

View on GitHub (pinned to e1c734241f)

Solutions

Wrap the value in a java.util.List whose elements match the method's parameter types in order
Use a single-argument equivalent method/property if one exists
If set from config, ensure the config value binds as a list (e.g. comma-separated values into a List-typed config property)

Example fix

// before
builder.property("resteasy.connectionTTL", "2000, MILLISECONDS");
// after
builder.property("resteasy.connectionTTL", List.of(2000L, TimeUnit.MILLISECONDS));

Defensive patterns

Strategy: type-guard

Validate before calling

Method m = Arrays.stream(ResteasyClientBuilder.class.getMethods())
    .filter(x -> x.getName().equals(methodName)).findFirst().orElse(null);
if (m != null && m.getParameterCount() > 1 && !(value instanceof List)) {
    throw new IllegalArgumentException(methodName + " requires a List value");
}

Type guard

static boolean isListValue(Object v) { return v instanceof List<?>; }

Try / catch

try {
    builder.property("resteasy." + name, value);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("List<>")) { value = List.of(value); /* retry or fix */ }
}

Prevention

Pass java.util.List for any multi-argument builder method
Match list element types to the method's parameter order and types
Avoid string-encoded argument tuples in config

When it happens

Trigger: Calling property("resteasy.someMultiArgMethod", someNonListValue) where ResteasyClientBuilder.someMultiArgMethod has parameterCount > 1, or configuring such a key with a scalar/string value.

Common situations: Configuring multi-argument builder options (e.g. host/port pairs) via YAML or .property() with a plain string; users expecting automatic conversion from a comma-separated string to arguments.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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