What causes "xxl-job method-jobhandler initMethod invalid, for[{}#{}] ." in xuxueli/xxl-job?

Declare a public/package no-arg method whose name matches @XxlJob(init=...).

xuxueli/xxl-job · error · RuntimeException

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

Error message

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

What it means

Thrown by registryJobHandler when @XxlJob(init="...") names a method that does not exist on the bean's class (NoSuchMethodException caught and rewrapped). The init lifecycle hook must be a declared no-arg method on the same class.

Source

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

                    "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;

        if (StringTool.isNotBlank(xxlJob.init())) {
            try {
                initMethod = clazz.getDeclaredMethod(xxlJob.init());
                initMethod.setAccessible(true);
            } catch (NoSuchMethodException e) {
                throw new RuntimeException("xxl-job method-jobhandler initMethod invalid, for[" + clazz + "#" + methodName + "] .");
            }
        }
        if (StringTool.isNotBlank(xxlJob.destroy())) {
            try {
                destroyMethod = clazz.getDeclaredMethod(xxlJob.destroy());
                destroyMethod.setAccessible(true);
            } catch (NoSuchMethodException e) {
                throw new RuntimeException("xxl-job method-jobhandler destroyMethod invalid, for[" + clazz + "#" + methodName + "] .");
            }
        }

        // registry jobhandler
        registryJobHandler(name, new MethodJobHandler(bean, executeMethod, initMethod, destroyMethod));

    }


    // ---------------------- job thread repository ----------------------

View on GitHub (pinned to e74c784f68)

Solutions

Declare a public/package no-arg method whose name matches @XxlJob(init=...).
Keep the init method on the same class that carries the @XxlJob execute method.
Remove init="..." from the annotation if no init lifecycle is needed.

Example fix

// before
@XxlJob(value="x", init="warmUp")
public ReturnT<String> execute(String p){...}
// no warmUp() method exists
// after
@XxlJob(value="x", init="warmUp")
public ReturnT<String> execute(String p){...}
public void warmUp(){ /* preload */ }

Defensive patterns

Strategy: validation

Validate before calling

// Verify the init method exists and is no-arg before registration
if (StringTool.isNotBlank(xxlJob.init())) {
    Method im = clazz.getDeclaredMethod(xxlJob.init());
    if (im.getParameterCount() != 0) throw new IllegalStateException("init must be no-arg");
}

Try / catch

try {
    xxlJobExecutor.start();
} catch (RuntimeException e) {
    log.error("handler init method invalid: {}", e.getMessage());
}

Prevention

Keep init methods no-arg and on the annotated class.
Update the annotation when renaming lifecycle methods.
Add a test that reflects over @XxlJob handlers and asserts their init/destroy methods exist.

When it happens

Trigger: A handler annotated @XxlJob(value="x", init="initMe") where initMe is not declared, has parameters, is on a superclass not seen by getDeclaredMethod, or was renamed/deleted.

Common situations: Renamed the init method but not the annotation; declared init with parameters (must be no-arg); method is private on a parent class and getDeclaredMethod only sees the concrete class.

Related errors

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