Tencent/matrix · error · ConfigurationException

Custom library loader is not supported in isolate process…

Error message

Custom library loader is not supported in isolate process warm-up mode.

What it means

WeChatBacktrace.configure() throws ConfigurationException when both mWarmUpInIsolateProcess is enabled and a custom mLibraryLoader is supplied. In isolate-process warm-up mode the child process performs native library loading itself and cannot accept a caller-supplied loader, so the combination is rejected at configuration time.

Solutions

1. Remove the setLibraryLoader(...) call from the BacktraceConfiguration.
2. Set the library loader to null: configuration.mLibraryLoader = null before configure().
3. Disable isolate-process warm-up (setWarmUpInIsolateProcess(false)) if the custom loader is required.

Example fix

// before
BacktraceConfiguration cfg = new BacktraceConfiguration();
cfg.setWarmUpInIsolateProcess(true);
cfg.setLibraryLoader(new ReLinker.Loader()); // throws

// after
BacktraceConfiguration cfg = new BacktraceConfiguration();
cfg.setWarmUpInIsolateProcess(true);
// use default loader; custom loader unsupported in isolate warm-up mode

if (config.isWarmUpInIsolateProcess() && config.getLibraryLoader() != null) {
    config.setLibraryLoader(null); // clear before configure()
}
WeChatBacktrace.configure(config);

try {
    WeChatBacktrace.configure(config);
} catch (ConfigurationException e) {
    MatrixLog.e(TAG, "invalid backtrace config: " + e.getMessage());
}

When it happens

Trigger: Building a BacktraceConfiguration with setWarmUpInIsolateProcess(true) and also calling setLibraryLoader(...), then calling WeChatBacktrace.configure(configuration) from a non-isolate process.

Common situations: Enabling isolate-process warm-up while keeping a previously configured custom ReLinker/SoLoader loader; merging configuration defaults where mLibraryLoader stays set after switching warm-up mode.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• Should not call this from main thread!
• LeakProcessor not found!!!
• config.delayMillis is empty
• Matrix init, Matrix should not be null.
• you must init Matrix sdk first

AI-assisted analysis of Tencent/matrix@3b8293bd65 (2026-09-08). Data as JSON: /api/errors/e2fb9ad84cc66038. Report an issue: GitHub.

Appendix: source

Thrown at matrix/matrix-android/matrix-backtrace/src/main/java/com/tencent/matrix/backtrace/WeChatBacktrace.java:211

    }

    private boolean runningInIsolateProcess(Configuration configuration) {
        String processName = ProcessUtil.getProcessNameByPid(configuration.mContext);
        if (processName != null && processName.endsWith(ISOLATE_PROCESS_SUFFIX)) {
            return true;
        }
        return false;
    }

    private void configure(Configuration configuration) {

        if (runningInIsolateProcess(configuration)) {
            MatrixLog.i(TAG, "Isolate process does not need any configuration.");
            return;
        }

        if (configuration.mWarmUpInIsolateProcess && configuration.mLibraryLoader != null) {
            throw new ConfigurationException("Custom library loader is not supported in " +
                    "isolate process warm-up mode.");
        }

        // Load backtrace library.
        loadLibrary(configuration.mLibraryLoader);

        // Init xlog
        XLogNative.setXLogger(configuration.mPathOfXLogSo);

        // Enable log
        enableLogger(configuration.mEnableLog);

        MatrixLog.i(TAG, configuration.toString());

        if (configuration.mBacktraceMode == Mode.Fp || configuration.mBacktraceMode == Mode.Dwarf) {
            WeChatBacktraceNative.setBacktraceMode(configuration.mBacktraceMode.value);
        }

View on GitHub (pinned to 3b8293bd65)