{"record":{"id":"e3fdaf9d3f8ecbe2","repo":"quarkusio/quarkus","slug":"unable-to-find-handler-class-make-sure-your-deplo-e3fdaf","errorCode":null,"errorMessage":"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","messagePattern":"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","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/amazon-lambda/runtime/src/main/java/io/quarkus/amazon/lambda/runtime/AmazonLambdaRecorder.java","lineNumber":133,"sourceCode":"\n            if (handlerDefinition == null && handlerStreamClass == null) {\n                String errorMessage = \"Unable to find handler class with name \" + runtimeConfig.getValue().handler().get()\n                        + \" make sure there is a handler class in the deployment with the correct @Named annotation\";\n                throw new IllegalStateException(errorMessage);\n            }\n        } else {\n            int unnamedTotal = unnamedHandlerDefinitions.size() + unnamedStreamHandlerClasses.size();\n            int namedTotal = namedHandlerDefinitions.size() + namedStreamHandlerClasses.size();\n\n            if (unnamedTotal > 1 || namedTotal > 1 || (unnamedTotal > 0 && namedTotal > 0)) {\n                String errorMessage = \"Multiple handler classes, either specify the quarkus.lambda.handler property, or make sure there is only a single \"\n                        + RequestHandler.class.getName() + \" or, \" + RequestStreamHandler.class.getName()\n                        + \" implementation in the deployment\";\n                throw new IllegalStateException(errorMessage);\n            } else if (unnamedTotal == 0 && namedTotal == 0) {\n                String errorMessage = \"Unable to find handler class, make sure your deployment includes a single \"\n                        + RequestHandler.class.getName() + \" or, \" + RequestStreamHandler.class.getName() + \" implementation\";\n                throw new IllegalStateException(errorMessage);\n            } else if ((unnamedTotal + namedTotal) == 1) {\n                if (!unnamedHandlerDefinitions.isEmpty()) {\n                    handlerDefinition = unnamedHandlerDefinitions.get(0);\n                } else if (!namedHandlerDefinitions.isEmpty()) {\n                    handlerDefinition = namedHandlerDefinitions.values().iterator().next();\n                } else if (!unnamedStreamHandlerClasses.isEmpty()) {\n                    handlerStreamClass = unnamedStreamHandlerClasses.get(0);\n                } else if (!namedStreamHandlerClasses.isEmpty()) {\n                    handlerStreamClass = namedStreamHandlerClasses.values().iterator().next();\n                }\n            }\n        }\n\n        if (handlerStreamClass != null) {\n            setStreamHandlerClass(handlerStreamClass);\n        } else {\n            initializeHandlerClass(handlerDefinition);\n        }","sourceCodeStart":115,"sourceCodeEnd":151,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/amazon-lambda/runtime/src/main/java/io/quarkus/amazon/lambda/runtime/AmazonLambdaRecorder.java#L115-L151","documentation":"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.","triggerScenarios":"Deploying a Lambda artifact whose codebase has no class implementing RequestHandler/RequestStreamHandler (and no named handler beans).","commonSituations":"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.","solutions":["Add a class implementing com.amazonaws.services.lambda.runtime.RequestHandler or RequestStreamHandler to the deployment","Verify the io.quarkus:quarkus-amazon-lambda extension is on the deployment's classpath","If multiple handlers exist, set quarkus.lambda.handler instead","Check your build packages the module containing the handler"],"exampleFix":"// before\n// no handler in deployment\n// after\npublic class MyHandler implements RequestHandler<Map<String,Object>, String> {\n    public String apply(Map<String,Object> event, Context ctx) { return \"ok\"; }\n}","handlingStrategy":"validation","validationCode":"// build-time sanity: at least one handler must exist\nif (countHandlerImplementations() == 0) {\n    throw new IllegalStateException(\"No RequestHandler/RequestStreamHandler in deployment\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Verify the quarkus-amazon-lambda extension is a dependency","Keep handler classes in packaged modules","Add an integration test that boots the Lambda and invokes the handler"],"tags":["configuration","missing-handler","amazon-lambda","deployment"],"backgroundTag":"missing-handler-class","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}