xuxueli/xxl-job · error · RuntimeException

xxl-job method-jobhandler name invalid, for[{}#{}] .

Error message

xxl-job method-jobhandler name invalid, for[{}#{}] .

What it means

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.

Source

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

    public IJobHandler registryJobHandler(String name, IJobHandler jobHandler){
        logger.info(">>>>>>>>>>> xxl-job register jobhandler success, name:{}, jobHandler:{}", name, jobHandler);
        return jobHandlerRepository.put(name, jobHandler);
    }

    /**
     * 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

View on GitHub (pinned to e74c784f68)

Solutions

1. Give the @XxlJob annotation a non-blank unique name: @XxlJob("demoJobHandler").
2. Ensure the name has non-whitespace content after trim.
3. Rebuild and restart so the handler registry re-scans.

Example fix

// before
@XxlJob("")
public ReturnT<String> execute(String param) { ... }
// after
@XxlJob("demoJobHandler")
public ReturnT<String> execute(String param) { ... }

// At scan time, reject blank @XxlJob names before registration
String name = xxlJob.value();
if (name == null || name.trim().isEmpty()) {
    throw new IllegalStateException("@XxlJob name blank on " + clazz + "#" + method.getName());
}

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

When it happens

Trigger: A bean method annotated @XxlJob("") or @XxlJob(" ") is scanned at startup; registration aborts with the offending class#method.

Common situations: Forgot to fill the @XxlJob name; refactored annotation and left value empty; copied a handler method and removed the name.

Related errors

• xxl-job jobhandler[{}] naming conflicts.
• >>>>>>>>>>> xxl-job load executor instance fail, please init
• xxl-job executor adminAddresses empty.
• xxl-job executor appname empty.
• xxl-job executor accessToken empty.

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