Tencent/matrix · error · RuntimeException

Matrix init, Matrix should not be null.

Error message

Matrix init, Matrix should not be null.

What it means

Matrix.init(Matrix) requires a non-null Matrix instance to install as the SDK singleton. If you pass null, the library throws immediately because there is no instance to register. This is a fail-fast guard at SDK entry.

Solutions

1. Pass a fully constructed Matrix (new Matrix.Builder(application)...build()) to Matrix.init.
2. Ensure any conditional construction path always returns a Matrix instance before calling init.
3. Only call Matrix.init after verifying the built object is non-null.

Example fix

// before
Matrix.init(buildMatrixOrNull(application));
// after
Matrix matrix = buildMatrixOrNull(application);
if (matrix != null) {
    Matrix.init(matrix);
}

Matrix matrix = buildMatrix(application);
if (matrix == null) throw new IllegalStateException("Matrix instance must not be null");
Matrix.init(matrix);

boolean canInitMatrix(Matrix m) { return m != null; }

try {
    Matrix.init(matrix);
} catch (RuntimeException e) {
    Log.e(TAG, "Matrix init failed", e);
}

When it happens

Trigger: Calling Matrix.init(null), e.g. when the Matrix instance is built conditionally or a factory returns null.

Common situations: Wiring Matrix in Application.onCreate with a nullable builder result; refactoring where the Matrix construction was removed but init call left; conditional feature flags that skip building Matrix.

Related errors

• matrix init, application is null
• you must init Matrix sdk first
• plugin duplicate init, application or plugin listener is…
• plugin start, plugin listener is null
• Both of invoker and fieldName can not be null or nil.

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

Appendix: source

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

        this.plugins = plugins;
        MatrixLifecycleOwnerInitializer.init(app, config);
        ProcessSupervisor.INSTANCE.init(app, config.getSupervisorConfig());
        for (Plugin plugin : plugins) {
            plugin.init(application, listener);
        }
    }

    public static void setLogIml(MatrixLog.MatrixLogImp imp) {
        MatrixLog.setMatrixLogImp(imp);
    }

    public static boolean isInstalled() {
        return sInstance != null;
    }

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

View on GitHub (pinned to 3b8293bd65)