Tencent/matrix · error · TaskInitException

---The Proguard mapping file 'mapping.txt' is not legal!

Error message

---The Proguard mapping file 'mapping.txt' is not legal!

What it means

UnusedResourcesTask.init() throws TaskInitException when a Proguard mapping file path is configured (config.getMappingFilePath() non-empty) but the file is not legal (missing/unreadable). Mapping is optional but must be valid when supplied, for resolving obfuscated code references.

Solutions

  1. Confirm mapping.txt exists at the configured path (regenerate via the release build)
  2. Fix the path in config.setMappingFilePath(...) or clear it if code references aren't needed
  3. Keep mapping.txt as a build artifact (retention) on CI before running the check

Example fix

// before
config.setMappingFilePath("build/outputs/mapping/release/mapping.txt"); // from old build
// after
config.setMappingFilePath("app/build/outputs/mapping/release/mapping.txt"); // freshly generated, exists
Defensive patterns

Strategy: validation

Validate before calling

String mp = config.getMappingFilePath();
if (mp != null && !mp.isEmpty() && !(new File(mp).isFile())) {
    throw new IllegalStateException("mapping.txt missing: " + mp);
}

Try / catch

try {
    task.init();
} catch (TaskInitException e) {
    log.error("mapping.txt invalid: " + e.getMessage());
}

Prevention

When it happens

Trigger: Setting mapping file path to a path from a previous build that was cleaned, or a typo'd/never-generated mapping.txt.

Common situations: Release builds with R8/ProGuard on CI where mapping.txt location changed or was deleted; passing minifiedBuild mapping path while building variant differs.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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

Appendix: source

Thrown at matrix/matrix-android/matrix-apk-canary/src/main/java/com/tencent/matrix/apk/model/task/UnusedResourcesTask.java:123

            throw new TaskInitException(TAG + "---APK-UNZIP-PATH can not be null!");
        }
        if (!params.containsKey(JobConstants.PARAM_R_TXT) || Util.isNullOrNil(params.get(JobConstants.PARAM_R_TXT))) {
            throw new TaskInitException(TAG + "---The File 'R.txt' can not be null!");
        }
        resourceTxt = new File(params.get(JobConstants.PARAM_R_TXT));
        if (!FileUtil.isLegalFile(resourceTxt)) {
            throw new TaskInitException(TAG + "---The Resource declarations file 'R.txt' is not legal!");
        }
        inputFile = new File(inputPath);
        if (!inputFile.exists()) {
            throw new TaskInitException(TAG + "---APK-UNZIP-PATH '" + inputPath + "' is not exist!");
        } else if (!inputFile.isDirectory()) {
            throw new TaskInitException(TAG + "---APK-UNZIP-PATH '" + inputPath + "' is not directory!");
        }
        if (!Util.isNullOrNil(config.getMappingFilePath())) {
            mappingTxt = new File(config.getMappingFilePath());
            if (!FileUtil.isLegalFile(mappingTxt)) {
                throw new TaskInitException(TAG + "---The Proguard mapping file 'mapping.txt' is not legal!");
            }
        }
        if (params.containsKey(JobConstants.PARAM_IGNORE_RESOURCES_LIST) && !Util.isNullOrNil(params.get(JobConstants.PARAM_IGNORE_RESOURCES_LIST))) {
            String[] ignoreRes = params.get(JobConstants.PARAM_IGNORE_RESOURCES_LIST).split(",");
            for (String ignore : ignoreRes) {
                ignoreSet.add(Util.globToRegexp(ignore));
            }
        }
        if (!Util.isNullOrNil(config.getResMappingFilePath())) {
            resMappingTxt = new File(config.getResMappingFilePath());
            if (!FileUtil.isLegalFile(resMappingTxt)) {
                throw new TaskInitException(TAG + "---The Resguard mapping file 'resguard-mapping.txt' is not legal!");
            }
        }

        File[] files = inputFile.listFiles();
        if (files != null) {
            for (File file : files) {

View on GitHub (pinned to 3b8293bd65)