xuxueli/xxl-job · error · RuntimeException

xxl-job jobhandler[{}] naming conflicts.

Error message

xxl-job jobhandler[{}] naming conflicts.

What it means

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.

Source

Thrown at xxl-job-core/src/main/java/com/xxl/job/core/executor/XxlJobExecutor.java:344

    }

    /**
     * registry JobHandler for method
     */
    protected void registryJobHandler(XxlJob xxlJob, Object bean, Method executeMethod){
        if (xxlJob == null) {
            return;
        }

        String name = xxlJob.value();
        //make and simplify the variables since they'll be called several times later
        Class<?> clazz = bean.getClass();
        String methodName = executeMethod.getName();
        if (name.trim().isEmpty()) {
            throw new RuntimeException("xxl-job method-jobhandler name invalid, for[" + clazz + "#" + methodName + "] .");
        }
        if (loadJobHandler(name) != null) {
            throw new RuntimeException("xxl-job jobhandler[" + name + "] naming conflicts.");
        }

        // execute method
        /*if (!(method.getParameterTypes().length == 1 && method.getParameterTypes()[0].isAssignableFrom(String.class))) {
            throw new RuntimeException("xxl-job method-jobhandler param-classtype invalid, for[" + bean.getClass() + "#" + method.getName() + "] , " +
                    "The correct method format like \" public ReturnT<String> execute(String param) \" .");
        }
        if (!method.getReturnType().isAssignableFrom(ReturnT.class)) {
            throw new RuntimeException("xxl-job method-jobhandler return-classtype invalid, for[" + bean.getClass() + "#" + method.getName() + "] , " +
                    "The correct method format like \" public ReturnT<String> execute(String param) \" .");
        }*/

        executeMethod.setAccessible(true);

        // init and destroy
        Method initMethod = null;
        Method destroyMethod = null;

View on GitHub (pinned to e74c784f68)

Solutions

1. Rename one of the conflicting @XxlJob values so each handler name is unique.
2. Search the codebase for the duplicated name and resolve the intended owner.
3. Avoid generic names like "jobHandler" that are likely to collide.

Example fix

// before - two methods both named "orderJob"
@XxlJob("orderJob") void a(){}
@XxlJob("orderJob") void b(){}
// after
@XxlJob("orderSyncJob")  void a(){}
@XxlJob("orderReportJob") void b(){}

// Detect duplicate @XxlJob names at startup before the executor does
Map<String, Method> seen = new HashMap<>();
for (Method m : bean.getClass().getDeclaredMethods()) {
    XxlJob a = m.getAnnotation(XxlJob.class);
    if (a != null) {
        if (seen.containsKey(a.value())) {
            throw new IllegalStateException("duplicate @XxlJob name: " + a.value());
        }
        seen.put(a.value(), m);
    }
}

try {
    xxlJobExecutor.start();
} catch (RuntimeException e) {
    log.error("handler registration failed: {}", e.getMessage());
}

When it happens

Trigger: Two bean methods carry the same @XxlJob("foo") value; the second registration attempt aborts startup naming the conflicting handler.

Common situations: 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.

Related errors

• xxl-job method-jobhandler name invalid, for[{}#{}] .
• xxl-job method-jobhandler initMethod invalid, for[{}#{}] .
• xxl-job method-jobhandler destroyMethod invalid, for[{}#{}]
• >>>>>>>>>>> xxl-job load executor instance fail, please init
• xxl-job executor adminAddresses empty.

AI-assisted analysis of xuxueli/xxl-job@e74c784f68 (2026-08-14). Data as JSON: /api/errors/18bebefef99e6ead. Report an issue: GitHub.