Tencent/matrix · error · GradleException

Matrix Plugin, Android Application plugin required.

Error message

Matrix Plugin, Android Application plugin required.

What it means

Matrix's Gradle plugin (`apply 'matrix'`) only works on Android application modules, so the plugin explicitly checks that the `com.android.application` plugin is already applied to the project during `apply()`. If it is not, a GradleException is thrown to fail the build early instead of producing broken instrumentation later. Matrix relies on AGP application-specific APIs (variants, APK artifacts) that only exist in app modules.

Solutions

1. Apply the Matrix plugin inside the module that applies `com.android.application` (typically `app/build.gradle`).
2. Ensure `apply plugin: 'com.android.application'` (or the `plugins { id 'com.android.application' }` block) appears before `apply plugin: 'matrix'` in the same module.
3. Remove the matrix plugin from the root project or any library modules and keep it only in the app module.

Example fix

// before (root build.gradle)
apply plugin: 'matrix'

// after (app/build.gradle)
apply plugin: 'com.android.application'
apply plugin: 'matrix'

// app/build.gradle
assert project.plugins.hasPlugin('com.android.application') : 'matrix plugin requires com.android.application'
apply plugin: 'matrix'

def isAppModule = { proj -> proj.plugins.hasPlugin('com.android.application') }

When it happens

Trigger: Applying the Matrix plugin from a project's build.gradle (root project), or from a library (`com.android.library`) / dynamic-feature module, or applying `matrix` before `com.android.application` in the same build script.

Common situations: Putting `apply plugin: 'matrix'` in the root build.gradle instead of the app module's build.gradle; forgetting to apply `com.android.application` first; moving the plugin to a shared convention plugin without ordering the plugin application correctly.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• This plugin must be applied after "com.android.library"…
• Debugging APK must be debuggable.
• apksigner returned with status: $ret
• [-] Either or should be applied when use this script.
• This plugin must be applied after "java" or…

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

Appendix: source

Thrown at matrix/matrix-android/matrix-gradle-plugin/src/main/kotlin/com/tencent/matrix/plugin/MatrixPlugin.kt:42

import com.tencent.matrix.trace.extension.MatrixTraceExtension
import org.gradle.api.GradleException
import org.gradle.api.Plugin
import org.gradle.api.Project
import org.gradle.api.plugins.ExtensionAware

class MatrixPlugin : Plugin<Project> {
    companion object {
        const val TAG = "Matrix.Plugin"
    }

    override fun apply(project: Project) {

        val matrix = project.extensions.create("matrix", MatrixExtension::class.java)
        val traceExtension = (matrix as ExtensionAware).extensions.create("trace", MatrixTraceExtension::class.java)
        val removeUnusedResourcesExtension = matrix.extensions.create("removeUnusedResources", MatrixRemoveUnusedResExtension::class.java)

        if (!project.plugins.hasPlugin("com.android.application")) {
            throw GradleException("Matrix Plugin, Android Application plugin required.")
        }

        project.afterEvaluate {
            Log.setLogLevel(matrix.logLevel)
        }

        MatrixTasksManager().createMatrixTasks(
                project.extensions.getByName("android") as AppExtension,
                project,
                traceExtension,
                removeUnusedResourcesExtension
        )
    }
}

View on GitHub (pinned to 3b8293bd65)