quarkusio/quarkus · error · IllegalStateException

Providing multiple BuiltInReaderOverrideBuildItem for the sa

Error message

Providing multiple BuiltInReaderOverrideBuildItem for the same readerClassName is not supported

What it means

BuiltInReaderOverrideBuildItem.toMap converts the list of built-in message body reader overrides into a map keyed by readerClassName. Because a map can hold only one override per key, providing two or more build items that override the same reader class makes the transformation ambiguous, so an IllegalStateException is thrown. It is a build-time consistency check protecting Quarkus extensions from silently dropping one extension's override.

Source

Thrown at extensions/resteasy-reactive/rest/deployment/src/main/java/io/quarkus/resteasy/reactive/server/deployment/BuiltInReaderOverrideBuildItem.java:36

    }

    public String getReaderClassName() {
        return readerClassName;
    }

    public String getOverrideClassName() {
        return overrideClassName;
    }

    public static Map<String, String> toMap(List<BuiltInReaderOverrideBuildItem> items) {
        if (items.isEmpty()) {
            return Collections.emptyMap();
        }
        Map<String, String> result = new HashMap<>();
        for (BuiltInReaderOverrideBuildItem item : items) {
            String previousOverride = result.put(item.getReaderClassName(), item.getOverrideClassName());
            if (previousOverride != null) {
                throw new IllegalStateException(
                        "Providing multiple BuiltInReaderOverrideBuildItem for the same readerClassName is not supported");
            }
        }
        return result;
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

Identify which extensions produce the duplicate (search the deployment classpath for BuiltInReaderOverrideBuildItem producers with the same readerClassName).
Remove one of the extensions or one of the producer build steps so only a single override exists per reader class.
If you own both producers, merge them into a single BuiltInReaderOverrideBuildItem or pick a more specific reader class to override.

Example fix

// before: two producers overriding the same reader
@BuildStep
BuiltInReaderOverrideBuildItem overrideA() {
    return new BuiltInReaderOverrideBuildItem("com.fasterxml.jackson.jaxrs.json.JacksonJaxbJsonProvider", MyProvider.class.getName());
}
@BuildStep // in another extension
BuiltInReaderOverrideBuildItem overrideB() { /* same readerClassName */ }

// after: single, merged override
@BuildStep
BuiltInReaderOverrideBuildItem override() {
    return new BuiltInReaderOverrideBuildItem(readerClassName, singleOverrideClass);
}

Defensive patterns

Strategy: validation

Validate before calling

// CI check: ensure each readerClassName appears in at most one BuiltInReaderOverrideBuildItem producer
Map<String, Long> dupes = allOverrides.stream()
    .collect(Collectors.groupingBy(BuiltInReaderOverrideBuildItem::getReaderClassName, Collectors.counting()));
List<String> conflicts = dupes.entrySet().stream()
    .filter(e -> e.getValue() > 1).map(Map.Entry::getKey).toList();
if (!conflicts.isEmpty()) throw new IllegalStateException("Duplicate reader overrides: " + conflicts);

Try / catch

// Deployment-time failure during augmentation; cannot be caught in app code.
// Catch it in a build/integration test that runs Quarkus augmentation:
try {
    Quarkus aug = new QuarkusBootstrap(...).setMode(QuarkusBootstrap.Mode.PRODUCTION).run();
} catch (IllegalStateException e) {
    if (e.getMessage().contains("multiple BuiltInReaderOverrideBuildItem")) {
        log.error("Two extensions override the same built-in reader", e);
    }
}

Prevention

Check dependency extensions for BuiltInReaderOverrideBuildItem producers before adding your own override
Only override a built-in reader class your own extension owns
Merge overrides into a single build item when multiple steps need the same reader

When it happens

Trigger: Two extensions (or two build steps in the same extension) produce BuiltInReaderOverrideBuildItem build items with the same getReaderClassName() value during RESTEasy Reactive server deployment.

Common situations: Two Quarkus extensions both overriding e.g. the Jackson or JSON-B built-in reader; an application adding its own override build item that collides with an extension's.

Related errors

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