xuxueli/xxl-job · critical · RuntimeException

>>>>>>>>>>> xxl-job load executor instance fail, please init

Error message

>>>>>>>>>>> xxl-job load executor instance fail, please initialize it.

What it means

Thrown by XxlJobExecutor.getInstance() when the static singleton field xxlJobExecutor is null. The singleton is only assigned inside start() (xxlJobExecutor = this), so any caller of getInstance() before a successful start() - or after the executor was never started - hits this.

Source

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

import java.util.List;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentMap;
import java.util.concurrent.TimeUnit;

/**
 * Created by xuxueli on 2016/3/2 21:14.
 */
public class XxlJobExecutor  {
    private static final Logger logger = LoggerFactory.getLogger(XxlJobExecutor.class);


    // ---------------------- instance ----------------------

    private static XxlJobExecutor xxlJobExecutor = null;
    public static XxlJobExecutor getInstance() {
        if (xxlJobExecutor == null) {
            throw new RuntimeException(">>>>>>>>>>> xxl-job load executor instance fail, please initialize it.");
        }
        return xxlJobExecutor;
    }


    // ---------------------- field ----------------------

    private String adminAddresses;                                  // admin address list, such as "http://address" or "http://address01,http://address02"
    private int timeout = 3;                                        // timeout by second, default 3s
    private boolean enabled = true;                                 // executor enable, default true
    private String appname;                                         // executor appname
    private String accessToken;                                     // access token
    private String ip;                                              // executor server-info
    private int port;
    private String address;                                         // executor registry-address: default use address to registry , otherwise use ip:port if address is null
    private String logPath = "/data/applogs/xxl-job/jobhandler";    // executor log-path
    private int logRetentionDays = 30;                              // executor log-retention-days
    private boolean glueEnabled = true;                             // executor glue (non-BEAN) task enable, default true

View on GitHub (pinned to e74c784f68)

Solutions

1. Ensure XxlJobExecutor.start() is called (e.g. via Spring @PostConstruct or a SmartLifecycle) before any code calls getInstance().
2. Check that the executor is enabled (enabled=true); a disabled executor returns from start() without binding the instance.
3. In tests, construct and start() the executor explicitly before exercising getInstance().

Example fix

// before
IJobHandler h = XxlJobExecutor.getInstance().loadJobHandler(name); // NPE-ish: not started
// after
XxlJobExecutor exec = new XxlJobExecutor();
exec.setAdminAddresses(addr); exec.setAppname(app); exec.setAccessToken(token);
exec.start(); // binds singleton
IJobHandler h = XxlJobExecutor.getInstance().loadJobHandler(name);

// Only call getInstance() after a successful start()
if (XxlJobExecutor.getInstance() == null) { // note: getInstance itself throws; track started flag instead
    throw new IllegalStateException("executor not started");
}

try {
    XxlJobExecutor.getInstance();
} catch (RuntimeException e) {
    log.error("executor not initialized; call start() first: {}", e.getMessage());
}

When it happens

Trigger: Calling XxlJobExecutor.getInstance() before XxlJobExecutor.start() completed, or in a context where the executor bean was never started (e.g. a test, a misconfigured Spring context, or a startup ordering problem).

Common situations: Application lifecycle race where a component autowires and queries the executor during construction before start() runs; unit tests that call core APIs without booting the executor; disabled executor (enabled=false) so start() returns early without binding the singleton.

Related errors

• xxl-job executor adminAddresses empty.
• xxl-job executor appname empty.
• xxl-job executor accessToken empty.
• xxl-job method-jobhandler name invalid, for[{}#{}] .
• xxl-job logPath cannot be empty

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