quarkusio/quarkus · error · IllegalArgumentException

RequestHandler class not found in the index: <handlerClassNa

Error message

RequestHandler class not found in the index: <handlerClassName>

What it means

RequestHandlerJandexUtil.discoverHandlerMethod looks up the configured handler class in the build-time Jandex index; index.getClassByName returned null, so the class name cannot be resolved to bytecode metadata for recording the handler.

Source

Thrown at extensions/amazon-lambda/deployment/src/main/java/io/quarkus/amazon/lambda/deployment/RequestHandlerJandexUtil.java:30

import org.jboss.jandex.ParameterizedType;
import org.jboss.jandex.Type;
import org.jboss.jandex.TypeVariable;

import com.amazonaws.services.lambda.runtime.RequestHandler;

public class RequestHandlerJandexUtil {

    private static final DotName REQUEST_HANDLER = DotName.createSimple(RequestHandler.class);
    private static final DotName OBJECT = DotName.createSimple("java.lang.Object");
    private static final DotName COLLECTION = DotName.createSimple(Collection.class);

    private RequestHandlerJandexUtil() {
    }

    public static RequestHandlerJandexDefinition discoverHandlerMethod(String handlerClassName, IndexView index) {
        ClassInfo handlerClass = index.getClassByName(handlerClassName);
        if (handlerClass == null) {
            throw new IllegalArgumentException("RequestHandler class not found in the index: " + handlerClassName);
        }

        MethodInfo concreteHandleRequestMethod = findConcreteHandleRequestMethod(handlerClass, index);
        if (concreteHandleRequestMethod == null) {
            throw new IllegalStateException(
                    "Unable to find a concrete handleRequest method on handler class " + handlerClass.name());
        }

        Map<String, Type> typeMap = new HashMap<>();
        InputOutputTypes inputOutputTypes = resolveInputOutputTypes(handlerClass.name(), index, typeMap);
        if (isUnresolved(inputOutputTypes)) {
            throw new IllegalStateException(
                    "Unable to resolve input and output types for handler class " + handlerClass.name());
        }

        return new RequestHandlerJandexDefinition(handlerClass, concreteHandleRequestMethod, inputOutputTypes);
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Fix the fully qualified class name in the lambda handler configuration to match the actual class
2. Ensure the class is in the application's own sources so it is Jandex-indexed at build time
3. If the handler is in a library jar, add a Jandex index to that jar (jandex-maven-plugin) or list it via quarkus.index-dependencies.<group>.artifact-id
4. Clean and rebuild so the index reflects recent renames

Example fix

# before
quarkus.lambda.handler.myfun.handler=com.acme.Handlr
# after
quarkus.lambda.handler.myfun.handler=com.acme.MyHandler

// pre-check before configuring
ClassInfo ci = index.getClassByName("com.acme.MyHandler");
if (ci == null) throw new IllegalArgumentException("Handler class not indexed: com.acme.MyHandler");

When it happens

Trigger: discoverHandlerMethod(handlerClassName, index) is called (e.g. from recordStaticInitHandlerClass for a configured lambda handler) and the index has no ClassInfo for that exact name.

Common situations: Typo or wrong package in the configured handler class name (quarkus.lambda.handler.<name>.handler class); class lives in an unindexed dependency jar; handler class was refactored/renamed but config still points at the old name.

Related errors

• Unable to find a concrete handleRequest method on handler cl
• Unable to resolve input and output types for handler class <
• The Amazon Lambda extensions are incompatible with the 'nati
• Multiple handler classes. You have a custom handler class a
• Unable to find handler class, make sure your deployment incl

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