quarkusio/quarkus · error · IllegalStateException

Unable to find handler class, make sure your deployment incl

Error message

Unable to find handler class, make sure your deployment includes a single io.quarkus.amazon.lambda.runtime.RequestHandler or, io.quarkus.amazon.lambda.runtime.RequestStreamHandler implementation

What it means

Thrown by AmazonLambdaRecorder.chooseHandlerClass during runtime handler selection when neither a named RequestHandler/RequestStreamHandler implementation matching the configured handler name nor any usable candidate could be located in the deployment. Selection first tries the quarkus.lambda.handler name against @Named beans and recorded handler definitions, then falls back to unnamed candidates; hitting this guard means the application did not expose exactly one io.quarkus.amazon.lambda.runtime.RequestHandler or RequestStreamHandler implementation for the recorder to instantiate.

Source

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

            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) {
            setStreamHandlerClass(handlerStreamClass);
        } else {
            initializeHandlerClass(handlerDefinition);
        }

View on GitHub (pinned to e1c734241f)

Solutions

1. Add a class implementing com.amazonaws.services.lambda.runtime.RequestHandler or RequestStreamHandler to the deployment
2. Verify the io.quarkus:quarkus-amazon-lambda extension is on the deployment's classpath
3. If multiple handlers exist, set quarkus.lambda.handler instead
4. Check your build packages the module containing the handler

Example fix

// before
// no handler in deployment
// after
public class MyHandler implements RequestHandler<Map<String,Object>, String> {
    public String apply(Map<String,Object> event, Context ctx) { return "ok"; }
}

// build-time sanity: at least one handler must exist
if (countHandlerImplementations() == 0) {
    throw new IllegalStateException("No RequestHandler/RequestStreamHandler in deployment");
}

When it happens

Trigger: Deploying a Lambda artifact whose codebase has no class implementing RequestHandler/RequestStreamHandler (and no named handler beans).

Common situations: Missing quarkus-amazon-lambda dependency so handler interfaces aren't recognized; handler class in a module not packaged; accidentally deleting/refactoring away the handler; plain function deployed with funqy-only code expecting different wiring.

Related errors

• Unable to find handler class with name <handler> make sure t
• Multiple handler classes, either specify the quarkus.lambda.
• Unknown cache type:
• Unable to determine the value type for '" + cacheName + "' R
• Failed to load application configuration

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