What causes "Multiple handler classes. You have a custom handler class and the extension. Please remove one of them from your deployment." in quarkusio/quarkus?

Remove your custom handler class (or the archetype-generated one) and rely on the provider extension's handler

quarkusio/quarkus · error · BuildException

Multiple handler classes. You have a custom handler class a

Error message

Multiple handler classes.  You have a custom handler class and the <provider> extension.  Please remove one of them from your deployment.

What it means

The Amazon Lambda deployment processor found both your own RequestHandler/RequestStreamHandler implementations and a handler provided by another extension (e.g. SQS, SNSS Event handler extension). Only one Lambda handler source may exist per deployment.

Source

Thrown at extensions/amazon-lambda/deployment/src/main/java/io/quarkus/amazon/lambda/deployment/AmazonLambdaProcessor.java:100

    @BuildStep
    List<AmazonLambdaBuildItem> discover(CombinedIndexBuildItem combinedIndexBuildItem,
            Optional<ProvidedAmazonLambdaHandlerBuildItem> providedLambda,
            BuildProducer<AdditionalBeanBuildItem> additionalBeanBuildItemBuildProducer,
            BuildProducer<ReflectiveHierarchyBuildItem> reflectiveHierarchy,
            BuildProducer<ReflectiveClassBuildItem> reflectiveClassBuildItemBuildProducer) throws BuildException {

        List<ClassInfo> requestHandlers = new ArrayList<>(
                combinedIndexBuildItem.getIndex().getAllKnownImplementations(REQUEST_HANDLER)
                        .stream().filter(INCLUDE_HANDLER_PREDICATE).toList());

        List<ClassInfo> streamHandlers = new ArrayList<>(combinedIndexBuildItem.getIndex()
                .getAllKnownImplementations(REQUEST_STREAM_HANDLER).stream().filter(INCLUDE_HANDLER_PREDICATE).toList());
        streamHandlers.addAll(combinedIndexBuildItem.getIndex()
                .getAllKnownSubclasses(SKILL_STREAM_HANDLER).stream().filter(INCLUDE_HANDLER_PREDICATE).toList());

        if ((!requestHandlers.isEmpty() || !streamHandlers.isEmpty()) && providedLambda.isPresent()) {
            throw new BuildException(
                    "Multiple handler classes.  You have a custom handler class and the " + providedLambda.get().getProvider()
                            + " extension.  Please remove one of them from your deployment.",
                    List.of());

        }
        AdditionalBeanBuildItem.Builder additionalBeansBuilder = AdditionalBeanBuildItem.builder().setUnremovable();
        List<AmazonLambdaBuildItem> amazonLambdas = new ArrayList<>();

        for (ClassInfo requestHandler : requestHandlers) {
            if (requestHandler.isAbstract()) {
                continue;
            }

            additionalBeansBuilder.addBeanClass(requestHandler.name().toString());
            amazonLambdas.add(new AmazonLambdaBuildItem(requestHandler.name().toString(), getCdiName(requestHandler), false));
        }

        for (ClassInfo streamHandler : streamHandlers) {

View on GitHub (pinned to e1c734241f)

Solutions

Remove your custom handler class (or the archetype-generated one) and rely on the provider extension's handler
Or remove the provider extension dependency if you intend to handle events yourself
Check dependencies for multiple quarkus-amazon-lambda-* provider modules and keep only one strategy

Example fix

// before
class MyHandler implements RequestHandler<SqsEvent, Void> { ... }
<dependency>io.quarkus:quarkus-amazon-lambda-sqs</dependency>
// after
// delete MyHandler, keep the quarkus-amazon-lambda-sqs dependency (or vice versa)

Defensive patterns

Strategy: validation

Prevention

Pick one handler strategy per deployment: custom class OR provider extension
Remove archetype sample handlers after adding provider extensions
Audit pom.xml for multiple quarkus-amazon-lambda-* provider modules
Run mvn quarkus:dev early to catch build-step conflicts

When it happens

Trigger: discover() runs at build time; requestHandlers/streamHandlers from the combined index are non-empty AND providedLambda (a provider extension's handler) is present.

Common situations: Adding quarkus-amazon-lambda-sqs (or another provider) to a project that also contains a custom implements RequestHandler class; leftover example handler class from an archetype after adding a provider extension.

Related errors

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