{"record":{"id":"5233318a0cf5e1fc","repo":"quarkusio/quarkus","slug":"unable-to-find-handler-class-with-name-handler-m","errorCode":null,"errorMessage":"Unable to find handler class with name <handler> make sure there is a handler class in the deployment with the correct @Named annotation","messagePattern":"Unable to find handler class with name <handler> make sure there is a handler class in the deployment with the correct @Named annotation","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/amazon-lambda/runtime/src/main/java/io/quarkus/amazon/lambda/runtime/AmazonLambdaRecorder.java","lineNumber":119,"sourceCode":"            objectWriter.writeValue(outputStream, response);\n        }\n    }\n\n    public void chooseHandlerClass(List<RequestHandlerDefinition> unnamedHandlerDefinitions,\n            Map<String, RequestHandlerDefinition> namedHandlerDefinitions,\n            List<Class<? extends RequestStreamHandler>> unnamedStreamHandlerClasses,\n            Map<String, Class<? extends RequestStreamHandler>> namedStreamHandlerClasses) {\n\n        RequestHandlerDefinition handlerDefinition = null;\n        Class<? extends RequestStreamHandler> handlerStreamClass = null;\n        if (runtimeConfig.getValue().handler().isPresent()) {\n            handlerDefinition = namedHandlerDefinitions.get(runtimeConfig.getValue().handler().get());\n            handlerStreamClass = namedStreamHandlerClasses.get(runtimeConfig.getValue().handler().get());\n\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()) {","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/amazon-lambda/runtime/src/main/java/io/quarkus/amazon/lambda/runtime/AmazonLambdaRecorder.java#L101-L137","documentation":"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.","triggerScenarios":"quarkus.lambda.handler=<name> set in config but no @Named(\"<name>\") RequestHandler or RequestStreamHandler bean exists in the deployment; or the name is misspelled.","commonSituations":"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.","solutions":["Set quarkus.lambda.handler to exactly match a @Named value on a RequestHandler/RequestStreamHandler bean","Annotate the intended handler with @Named(\"<value from config>\")","Remove quarkus.lambda.handler if you only have one handler","List @Named handler beans in the deployment and cross-check the property value"],"exampleFix":"// before\n# application.properties\nquarkus.lambda.handler=orders  # no bean named \"orders\"\n// after\n# application.properties\nquarkus.lambda.handler=OrderHandler\n\n@Named(\"OrderHandler\")\npublic class OrderHandler implements RequestHandler<...> {...}","handlingStrategy":"validation","validationCode":"// fail fast: verify configured handler name matches a @Named bean\nString name = config.getValue(\"quarkus.lambda.handler\");\nif (name != null && !namedHandlers.containsKey(name)) {\n    throw new IllegalArgumentException(\"No @Named handler bean: \" + name);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep quarkus.lambda.handler values in sync with @Named annotations","Add a startup/test check that each configured handler name resolves","Avoid hand-editing handler names in env-specific configs without review"],"tags":["configuration","cdi","named-bean","amazon-lambda"],"backgroundTag":"missing-config-property","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-15T02:17:10.978Z"}