quarkusio/quarkus · error · IllegalStateException

Unable to find handler class with name <handler> make sure t

Error message

Unable to find handler class with name <handler> make sure there is a handler class in the deployment with the correct @Named annotation

What it means

When quarkus.lambda.handler is set, AmazonLambdaRecorder.chooseHandlerClass looks up the named handler among @Named CDI handler definitions and stream handler classes. If no bean with that name exists, it throws IllegalStateException telling you to add a handler class with the correct @Named annotation.

Source

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

            objectWriter.writeValue(outputStream, response);
        }
    }

    public void chooseHandlerClass(List<RequestHandlerDefinition> unnamedHandlerDefinitions,
            Map<String, RequestHandlerDefinition> namedHandlerDefinitions,
            List<Class<? extends RequestStreamHandler>> unnamedStreamHandlerClasses,
            Map<String, Class<? extends RequestStreamHandler>> namedStreamHandlerClasses) {

        RequestHandlerDefinition handlerDefinition = null;
        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()) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Set quarkus.lambda.handler to exactly match a @Named value on a RequestHandler/RequestStreamHandler bean
2. Annotate the intended handler with @Named("<value from config>")
3. Remove quarkus.lambda.handler if you only have one handler
4. List @Named handler beans in the deployment and cross-check the property value

Example fix

// before
# application.properties
quarkus.lambda.handler=orders  # no bean named "orders"
// after
# application.properties
quarkus.lambda.handler=OrderHandler

@Named("OrderHandler")
public class OrderHandler implements RequestHandler<...> {...}

// fail fast: verify configured handler name matches a @Named bean
String name = config.getValue("quarkus.lambda.handler");
if (name != null && !namedHandlers.containsKey(name)) {
    throw new IllegalArgumentException("No @Named handler bean: " + name);
}

When it happens

Trigger: quarkus.lambda.handler=<name> set in config but no @Named("<name>") RequestHandler or RequestStreamHandler bean exists in the deployment; or the name is misspelled.

Common situations: Multi-handler projects where the property value doesn't match any @Named value; renaming a handler class without updating config; environment-specific config carrying a stale handler name.

Related errors

• Multiple handler classes, either specify the quarkus.lambda.
• Unable to find handler class, make sure your deployment incl
• Invalid @GrpcClient `${targetInfo}` - client name cannot be
• Unable to find the GrpcClientConfigProvider
• Unable to retrieve the gRPC Channel ${name}

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