Tencent/matrix · error · RuntimeException

matrix init, application is null

Error message

matrix init, application is null

What it means

Thrown from Matrix.Builder's constructor when the Application argument is null. The Matrix library requires a valid Application context to initialize its plugins and lifecycle callbacks, so constructing a Builder without one makes the entire Matrix initialization invalid and fails fast with a RuntimeException instead of failing later in plugin setup.

Solutions

1. Pass the real Application instance (Activity.getApplication() or the application parameter of Application.onCreate).
2. Cast the context with (Application) context.getApplicationContext() instead of the raw context.
3. Defer Builder construction until the Application is available.

Example fix

// before
Matrix.Builder builder = new Matrix.Builder((Application) context);
// after
Matrix.Builder builder = new Matrix.Builder((Application) context.getApplicationContext());

Application app = context.getApplicationContext() instanceof Application
    ? (Application) context.getApplicationContext() : null;
if (app != null) {
    new Matrix.Builder(app);
}

Application asApp(Context c) {
    return c instanceof Application ? (Application) c : null;
}

try {
    new Matrix.Builder(app);
} catch (RuntimeException e) {
    Log.e(TAG, "Builder requires non-null Application", e);
}

When it happens

Trigger: new Matrix.Builder(null), typically when getApplication()/getApplicationInfo() returns null or a context is cast incorrectly.

Common situations: Passing an Activity context wrongly cast to Application; calling the Builder before the Application exists (e.g. in a ContentProvider with wrong context); mocking in unit tests without an Application.

Related errors

• Matrix init, Matrix should not be 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/bbcfc511b1bf11db. Report an issue: GitHub.

Appendix: source

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

        return null;
    }

    public static class Builder {
        private final Application application;

        private PluginListener   pluginListener;

        private MatrixLifecycleConfig mLifecycleConfig = new MatrixLifecycleConfig(); // default config

//        private SupervisorConfig supervisorConfig;
//        private boolean          enableFgServiceMonitor;
//        private boolean          enableOverlayWindowMonitor;

        private final HashSet<Plugin> plugins = new HashSet<>();

        public Builder(Application app) {
            if (app == null) {
                throw new RuntimeException("matrix init, application is null");
            }
            this.application = app;
        }

        public Builder plugin(Plugin plugin) {
            String tag = plugin.getTag();
            for (Plugin exist : plugins) {
                if (tag.equals(exist.getTag())) {
                    throw new RuntimeException(String.format("plugin with tag %s is already exist", tag));
                }
            }
            plugins.add(plugin);
            return this;
        }

        public Builder pluginListener(PluginListener pluginListener) {
            this.pluginListener = pluginListener;
            return this;

View on GitHub (pinned to 3b8293bd65)