{"record":{"id":"18bebefef99e6ead","repo":"xuxueli/xxl-job","slug":"xxl-job-jobhandler-naming-conflicts","errorCode":null,"errorMessage":"xxl-job jobhandler[{}] naming conflicts.","messagePattern":"xxl-job jobhandler\\[(.+?)\\] naming conflicts\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"xxl-job-core/src/main/java/com/xxl/job/core/executor/XxlJobExecutor.java","lineNumber":344,"sourceCode":"    }\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\n        Method initMethod = null;\n        Method destroyMethod = null;\n","sourceCodeStart":326,"sourceCodeEnd":362,"githubUrl":"https://github.com/xuxueli/xxl-job/blob/e74c784f68f81fa89cb350913ef15794865d7b12/xxl-job-core/src/main/java/com/xxl/job/core/executor/XxlJobExecutor.java#L326-L362","documentation":"Thrown by XxlJobExecutor.registryJobHandler when a @XxlJob name is already registered to another handler. Handler names must be unique within an executor because the admin triggers by name alone.","triggerScenarios":"Two bean methods carry the same @XxlJob(\"foo\") value; the second registration attempt aborts startup naming the conflicting handler.","commonSituations":"Copy-pasted a handler method without renaming; two modules each define a handler with the same generic name; a built-in IJobHandler name collides with a new @XxlJob method.","solutions":["Rename one of the conflicting @XxlJob values so each handler name is unique.","Search the codebase for the duplicated name and resolve the intended owner.","Avoid generic names like \"jobHandler\" that are likely to collide."],"exampleFix":"// before - two methods both named \"orderJob\"\n@XxlJob(\"orderJob\") void a(){}\n@XxlJob(\"orderJob\") void b(){}\n// after\n@XxlJob(\"orderSyncJob\")  void a(){}\n@XxlJob(\"orderReportJob\") void b(){}","handlingStrategy":"validation","validationCode":"// Detect duplicate @XxlJob names at startup before the executor does\nMap<String, Method> seen = new HashMap<>();\nfor (Method m : bean.getClass().getDeclaredMethods()) {\n    XxlJob a = m.getAnnotation(XxlJob.class);\n    if (a != null) {\n        if (seen.containsKey(a.value())) {\n            throw new IllegalStateException(\"duplicate @XxlJob name: \" + a.value());\n        }\n        seen.put(a.value(), m);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    xxlJobExecutor.start();\n} catch (RuntimeException e) {\n    log.error(\"handler registration failed: {}\", e.getMessage());\n}","preventionTips":["Run a startup scan that fails fast on duplicate handler names.","Avoid generic handler names likely to collide.","Keep one canonical handler per business name."],"tags":["jobhandler","annotation","startup","duplicate"],"backgroundTag":null,"analyzedSha":"e74c784f68f81fa89cb350913ef15794865d7b12","analyzedAt":"2026-08-14T04:22:43.715Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}