Tencent/matrix · error · RuntimeException

you must init Matrix sdk first

Error message

you must init Matrix sdk first

What it means

Matrix.with() returns the installed Matrix singleton; if the SDK was never initialized (or init has not completed), sInstance is null and the library throws. This guards all subsequent plugin access against an uninitialized SDK.

Solutions

1. Call Matrix.init(new Matrix.Builder(application)...build()) in Application.onCreate before any Matrix.with() usage.
2. Gate all Matrix.with() calls behind Matrix.isInstalled().
3. Ensure every process that uses Matrix runs its own initialization.

Example fix

// before
Matrix.with().startAllPlugins();
// after
if (Matrix.isInstalled()) {
    Matrix.with().startAllPlugins();
}

if (!Matrix.isInstalled()) {
    Matrix.init(new Matrix.Builder(app).build());
}

boolean matrixReady() { return Matrix.isInstalled(); }

try {
    Matrix.with().startAllPlugins();
} catch (RuntimeException e) {
    Log.e(TAG, "Matrix not initialized", e);
}

When it happens

Trigger: Calling Matrix.with() before Matrix.init(...), after init failed, or from a process (e.g. :push, webview process) where init was never executed.

Common situations: Accessing Matrix from a ContentProvider or multi-process code path that runs before Application.onCreate; forgetting Matrix.init in a new Application class; app crash-restart paths where init is skipped.

Related errors

• Matrix init, Matrix should not be null.
• matrix init, application is null
• plugin duplicate init, application or plugin listener is…
• Call #init() first!
• <getTag()> is not yet init!

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

Appendix: source

Thrown at matrix/matrix-android/matrix-android-lib/src/main/java/com/tencent/matrix/Matrix.java:77

    }

    public static Matrix init(Matrix matrix) {
        if (matrix == null) {
            throw new RuntimeException("Matrix init, Matrix should not be null.");
        }
        synchronized (Matrix.class) {
            if (sInstance == null) {
                sInstance = matrix;
            } else {
                MatrixLog.e(TAG, "Matrix instance is already set. this invoking will be ignored");
            }
        }
        return sInstance;
    }

    public static Matrix with() {
        if (sInstance == null) {
            throw new RuntimeException("you must init Matrix sdk first");
        }
        return sInstance;
    }

    public void startAllPlugins() {
        for (Plugin plugin : plugins) {
            plugin.start();
        }
    }

    public void stopAllPlugins() {
        for (Plugin plugin : plugins) {
            plugin.stop();
        }
    }

    public void destroyAllPlugins() {
        for (Plugin plugin : plugins) {

View on GitHub (pinned to 3b8293bd65)