quarkusio/quarkus · error · IllegalStateException

Multiple handler classes, either specify the quarkus.lambda.

Error message

Multiple handler classes, either specify the quarkus.lambda.handler property, or make sure there is only a single io.quarkus.amazon.lambda.runtime.RequestHandler or, io.quarkus.amazon.lambda.runtime.RequestStreamHandler implementation in the deployment

What it means

chooseHandlerClass throws this when no handler is selected via quarkus.lambda.handler and the deployment contains more than one candidate — multiple unnamed handlers, multiple named handlers, or a mix — so the recorder cannot pick one unambiguously.

Source

Thrown at extensions/amazon-lambda/runtime/src/main/java/io/quarkus/amazon/lambda/runtime/AmazonLambdaRecorder.java:129

        Class<? extends RequestStreamHandler> handlerStreamClass = null;
        if (runtimeConfig.getValue().handler().isPresent()) {
            handlerDefinition = namedHandlerDefinitions.get(runtimeConfig.getValue().handler().get());
            handlerStreamClass = namedStreamHandlerClasses.get(runtimeConfig.getValue().handler().get());

            if (handlerDefinition == null && handlerStreamClass == null) {
                String errorMessage = "Unable to find handler class with name " + runtimeConfig.getValue().handler().get()
                        + " make sure there is a handler class in the deployment with the correct @Named annotation";
                throw new IllegalStateException(errorMessage);
            }
        } else {
            int unnamedTotal = unnamedHandlerDefinitions.size() + unnamedStreamHandlerClasses.size();
            int namedTotal = namedHandlerDefinitions.size() + namedStreamHandlerClasses.size();

            if (unnamedTotal > 1 || namedTotal > 1 || (unnamedTotal > 0 && namedTotal > 0)) {
                String errorMessage = "Multiple handler classes, either specify the quarkus.lambda.handler property, or make sure there is only a single "
                        + RequestHandler.class.getName() + " or, " + RequestStreamHandler.class.getName()
                        + " implementation in the deployment";
                throw new IllegalStateException(errorMessage);
            } else if (unnamedTotal == 0 && namedTotal == 0) {
                String errorMessage = "Unable to find handler class, make sure your deployment includes a single "
                        + RequestHandler.class.getName() + " or, " + RequestStreamHandler.class.getName() + " implementation";
                throw new IllegalStateException(errorMessage);
            } else if ((unnamedTotal + namedTotal) == 1) {
                if (!unnamedHandlerDefinitions.isEmpty()) {
                    handlerDefinition = unnamedHandlerDefinitions.get(0);
                } else if (!namedHandlerDefinitions.isEmpty()) {
                    handlerDefinition = namedHandlerDefinitions.values().iterator().next();
                } else if (!unnamedStreamHandlerClasses.isEmpty()) {
                    handlerStreamClass = unnamedStreamHandlerClasses.get(0);
                } else if (!namedStreamHandlerClasses.isEmpty()) {
                    handlerStreamClass = namedStreamHandlerClasses.values().iterator().next();
                }
            }
        }

        if (handlerStreamClass != null) {

View on GitHub (pinned to e1c734241f)

Solutions

Set quarkus.lambda.handler to the exact handler bean name (or @Named value) of the intended handler
Mark handlers with @Named and reference the chosen name in config
Split handlers into separate deployments if each Lambda needs its own artifact

Example fix

// before
// two handlers, no config
// after
# application.properties
quarkus.lambda.handler=OrderHandler

Defensive patterns

Strategy: validation

Validate before calling

int candidates = countHandlerImplementations();
if (candidates > 1 && config.getValue("quarkus.lambda.handler") == null) {
    throw new IllegalStateException("Set quarkus.lambda.handler when deploying multiple handlers");
}

Prevention

Always set quarkus.lambda.handler in multi-handler deployments
Use @Named on every handler for explicit selection
Split unrelated handlers into separate artifacts

When it happens

Trigger: Deploying two or more RequestHandler/RequestStreamHandler implementations without setting quarkus.lambda.handler.

Common situations: Projects accumulating several Lambda handlers in one deployment; adding a second handler for a new function while sharing the artifact.

Related errors

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