Tencent/matrix · error · GradleException

the path of Matrix-ApkChecker not found!

Error message

the path of Matrix-ApkChecker not found!

What it means

The same validation method throws this error when `pathOfApkChecker` is null or empty entirely — i.e. the ApkChecker tool path was never configured, though the V2 removeUnusedResources task requires it to analyze the APK.

Solutions

  1. Set `pathOfApkChecker` in the removeUnusedResources extension to the full path of the Matrix ApkChecker jar.
  2. Build the ApkChecker from the Matrix repo (`:matrix-apk-checker`) or take the released jar and reference it.
  3. Switch to the V1 RemoveUnusedResourcesTask if checker analysis is not needed.

Example fix

// before
matrix {
  removeUnusedResources {
    // pathOfApkChecker missing
  }
}

// after
matrix {
  removeUnusedResources {
    pathOfApkChecker = project.rootDir.absolutePath + "/tools/matrix-apk-checker.jar"
  }
}
Defensive patterns

Strategy: validation

Validate before calling

assert ext.pathOfApkChecker?.trim() : 'pathOfApkChecker is required by removeUnusedResources V2'

Type guard

def hasApkChecker = { String p -> p != null && !p.trim().isEmpty() }

Try / catch

try { ... } catch (GradleException e) { if (e.message.contains('ApkChecker not found')) { logger.error('Set pathOfApkChecker in the matrix extension') } throw e }

Prevention

When it happens

Trigger: `parametersInvalidation` runs with `Util.isNullOrNil(pathOfApkChecker)` true — the extension property was never set in the matrix removeUnusedResources config.

Common situations: Adding `matrix { removeUnusedResources { ... } }` with defaults and forgetting the required `pathOfApkChecker`; migrating from V1 task (which doesn't need it) to V2; typos in the property name so the value never lands.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at matrix/matrix-android/matrix-gradle-plugin/src/main/kotlin/com/tencent/matrix/plugin/task/RemoveUnusedResourcesTaskV2.kt:477

                            for (m in 0 until fileList.size()) {
                                resultOfDuplicates[md5.toString()]?.add(fileList.get(m).asString)
                            }
                        }
                    }
                }
            }
        }
    }

    private fun parametersInvalidation() {

        // Validate path of ApkChecker tool
        if (!Util.isNullOrNil(pathOfApkChecker)) {
            if (!File(pathOfApkChecker).exists()) {
                throw GradleException("the path of Matrix-ApkChecker $pathOfApkChecker is not exist!")
            }
        } else {
            throw GradleException("the path of Matrix-ApkChecker not found!")
        }

        // Validate path of Zipalign tool
        if (isZipAlignEnabled) {
            if (Util.isNullOrNil(pathOfZipAlign)) {
                throw GradleException("Need zip align apk but the path of zipalign is not specified!")
            } else if (!File(pathOfZipAlign).exists()) {
                throw GradleException("Need zipalign apk but $pathOfZipAlign is not exist!")
            }
        }

        // Validate path of signing
        if (isSigningEnabled) {
            if (Util.isNullOrNil(pathOfApkSigner)) {
                throw GradleException("Need signing apk but the path of apksigner is not specified!")
            } else if (!File(pathOfApkSigner).exists()) {
                throw GradleException("Need signing apk but $pathOfApkSigner is not exist!")
            } else if (AgpCompat.getSigningConfig(variant) == null) {

View on GitHub (pinned to 3b8293bd65)