{"record":{"id":"2b8180d0b89fdadc","repo":"xuxueli/xxl-job","slug":"xxl-job-method-jobhandler-name-invalid-for","errorCode":null,"errorMessage":"xxl-job method-jobhandler name invalid, for[{}#{}] .","messagePattern":"xxl-job method-jobhandler name invalid, for\\[(.+?)#(.+?)\\] \\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"xxl-job-core/src/main/java/com/xxl/job/core/executor/XxlJobExecutor.java","lineNumber":341,"sourceCode":"    public IJobHandler registryJobHandler(String name, IJobHandler jobHandler){\n        logger.info(\">>>>>>>>>>> xxl-job register jobhandler success, name:{}, jobHandler:{}\", name, jobHandler);\n        return jobHandlerRepository.put(name, jobHandler);\n    }\n\n    /**\n     * registry JobHandler for method\n     */\n    protected void registryJobHandler(XxlJob xxlJob, Object bean, Method executeMethod){\n        if (xxlJob == null) {\n            return;\n        }\n\n        String name = xxlJob.value();\n        //make and simplify the variables since they'll be called several times later\n        Class<?> clazz = bean.getClass();\n        String methodName = executeMethod.getName();\n        if (name.trim().isEmpty()) {\n            throw new RuntimeException(\"xxl-job method-jobhandler name invalid, for[\" + clazz + \"#\" + methodName + \"] .\");\n        }\n        if (loadJobHandler(name) != null) {\n            throw new RuntimeException(\"xxl-job jobhandler[\" + name + \"] naming conflicts.\");\n        }\n\n        // execute method\n        /*if (!(method.getParameterTypes().length == 1 && method.getParameterTypes()[0].isAssignableFrom(String.class))) {\n            throw new RuntimeException(\"xxl-job method-jobhandler param-classtype invalid, for[\" + bean.getClass() + \"#\" + method.getName() + \"] , \" +\n                    \"The correct method format like \\\" public ReturnT<String> execute(String param) \\\" .\");\n        }\n        if (!method.getReturnType().isAssignableFrom(ReturnT.class)) {\n            throw new RuntimeException(\"xxl-job method-jobhandler return-classtype invalid, for[\" + bean.getClass() + \"#\" + method.getName() + \"] , \" +\n                    \"The correct method format like \\\" public ReturnT<String> execute(String param) \\\" .\");\n        }*/\n\n        executeMethod.setAccessible(true);\n\n        // init and destroy","sourceCodeStart":323,"sourceCodeEnd":359,"githubUrl":"https://github.com/xuxueli/xxl-job/blob/e74c784f68f81fa89cb350913ef15794865d7b12/xxl-job-core/src/main/java/com/xxl/job/core/executor/XxlJobExecutor.java#L323-L359","documentation":"Thrown by XxlJobExecutor.registryJobHandler when a method annotated @XxlJob has a value that is empty after trimming. The annotation value is the handler name the admin triggers against, so an empty name is unusable.","triggerScenarios":"A bean method annotated @XxlJob(\"\") or @XxlJob(\"   \") is scanned at startup; registration aborts with the offending class#method.","commonSituations":"Forgot to fill the @XxlJob name; refactored annotation and left value empty; copied a handler method and removed the name.","solutions":["Give the @XxlJob annotation a non-blank unique name: @XxlJob(\"demoJobHandler\").","Ensure the name has non-whitespace content after trim.","Rebuild and restart so the handler registry re-scans."],"exampleFix":"// before\n@XxlJob(\"\")\npublic ReturnT<String> execute(String param) { ... }\n// after\n@XxlJob(\"demoJobHandler\")\npublic ReturnT<String> execute(String param) { ... }","handlingStrategy":"validation","validationCode":"// At scan time, reject blank @XxlJob names before registration\nString name = xxlJob.value();\nif (name == null || name.trim().isEmpty()) {\n    throw new IllegalStateException(\"@XxlJob name blank on \" + clazz + \"#\" + method.getName());\n}","typeGuard":null,"tryCatchPattern":"try {\n    xxlJobExecutor.start();\n} catch (RuntimeException e) {\n    log.error(\"handler registration failed: {}\", e.getMessage());\n}","preventionTips":["Always provide a non-blank @XxlJob name.","Add a compile/test-time scan that asserts every @XxlJob has a name.","Use a naming convention to avoid blanks."],"tags":["jobhandler","annotation","startup","configuration"],"backgroundTag":null,"analyzedSha":"e74c784f68f81fa89cb350913ef15794865d7b12","analyzedAt":"2026-08-14T04:22:43.715Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}