quarkusio/quarkus · error · RuntimeException

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

At build time the processor must record the single handler class for static init; the index found no implementations of RequestHandler or RequestStreamHandler (and no configured lambda), so no handler exists to deploy.

Source

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

                recorder.setHandlerClass(toRequestHandlerDefinition(requestHandlerJandexDefinition, context));
            }
        } else if (lambdas != null && lambdas.size() == 1) {
            AmazonLambdaBuildItem item = lambdas.get(0);
            if (item.isStreamHandler()) {
                Class<? extends RequestStreamHandler> handlerClass = (Class<? extends RequestStreamHandler>) context
                        .classProxy(item.getHandlerClass());
                recorder.setStreamHandlerClass(handlerClass);

            } else {
                RequestHandlerJandexDefinition requestHandlerJandexDefinition = RequestHandlerJandexUtil
                        .discoverHandlerMethod(item.getHandlerClass(), index.getComputingIndex());
                registerForReflection(requestHandlerJandexDefinition, reflectiveMethods, reflectiveHierarchies);
                recorder.setHandlerClass(toRequestHandlerDefinition(requestHandlerJandexDefinition, context));
            }
        } else if (lambdas == null || lambdas.isEmpty()) {
            String errorMessage = "Unable to find handler class, make sure your deployment includes a single "
                    + RequestHandler.class.getName() + " or " + RequestStreamHandler.class.getName() + " implementation";
            throw new RuntimeException(errorMessage);
        }
    }

    @BuildStep
    @Record(ExecutionTime.RUNTIME_INIT)
    public void recordBeanContainer(BeanContainerBuildItem beanContainerBuildItem,
            AmazonLambdaRecorder recorder,
            // try to order this after service recorders
            List<ServiceStartBuildItem> orderServicesFirst) {
        recorder.setBeanContainer(beanContainerBuildItem.getValue());

    }

    @BuildStep
    @Record(ExecutionTime.RUNTIME_INIT)
    public void recordHandlerClass(CombinedIndexBuildItem index,
            List<AmazonLambdaBuildItem> lambdas,
            Optional<ProvidedAmazonLambdaHandlerBuildItem> providedLambda,

View on GitHub (pinned to e1c734241f)

Solutions

1. Add a class implementing io.quarkus.amazon.lambda.runtime.RequestHandler or RequestStreamHandler to your application
2. Alternatively configure an explicit handler via application properties (quarkus.lambda.handler map) if using a provider
3. Ensure the handler class is in a module that gets Jandex-indexed (application classes are indexed automatically; external jars need a jandex index or quarkus.index-dependencies)
4. Check package spelling: implement Quarkus's runtime interfaces, not raw com.amazonaws.services.lambda.runtime.RequestHandler

Example fix

// after
public class MyHandler implements io.quarkus.amazon.lambda.runtime.RequestHandler<ApiGatewayProxyRequestEvent, ApiGatewayProxyResponseEvent> {
  public ApiGatewayProxyResponseEvent handleRequest(ApiGatewayProxyRequestEvent event, Context context) { ... }
}

// build-time check: fail compilation if no handler
assertTrue(index.getAllKnownImplementors("io.quarkus.amazon.lambda.runtime.RequestHandler").size() > 0 || lambdaConfigConfigured);

When it happens

Trigger: recordStaticInitHandlerClass runs when neither the RequestHandler nor RequestStreamHandler branch found a class and the lambdas list from configuration is null/empty.

Common situations: Fresh project with the Lambda extension but no class implementing RequestHandler/RequestStreamHandler; handler class not annotated/packaged so Jandex indexing missed it (e.g. in a separate unindexed jar); renamed/deleted handler after adding the extension.

Related errors

• The Amazon Lambda extensions are incompatible with the 'nati
• Multiple handler classes. You have a custom handler class a
• RequestHandler class not found in the index: <handlerClassNa
• Unable to find a concrete handleRequest method on handler cl
• Unable to resolve input and output types for handler class <

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