Tencent/matrix · error · TaskInitException

---The Resguard mapping file 'resguard-mapping.txt' is not…

Error message

---The Resguard mapping file 'resguard-mapping.txt' is not legal!

What it means

UnusedResourcesTask.init() throws TaskInitException when a resguard mapping file path is configured (config.getResMappingFilePath()) but the file is not legal (missing/unreadable). Resguard mapping is used when AndResGuard renamed resources.

Solutions

Verify resguard-mapping.txt exists at the configured path (run AndResGuard first)
Update config.setResMappingFilePath(...) to the current AndResGuard output path
Remove the resguard mapping config if the APK was not processed by AndResGuard

Example fix

// before
config.setResMappingFilePath("build/outputs/resguard-mapping.txt");
// after
config.setResMappingFilePath("app/build/outputs/apk/release/AndResGuard/resguard-mapping.txt"); // exists after resguard runs

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

Run AndResGuard before the unused-resources check
Resolve the resguard mapping path from the AndResGuard extension output, not hardcoded strings
Only configure resguard mapping for resguard-processed APKs

When it happens

Trigger: Setting resguard mapping path to a non-existent or unreadable resguard-mapping.txt, e.g., after cleaning the AndResGuard output.

Common situations: Projects using AndResGuard where the mapping output path changed between versions or the check runs before resguard completes.

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/abe968f5f7a2599d. 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:135

        } 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) {
                if (file.isFile() && file.getName().endsWith(ApkConstants.DEX_FILE_SUFFIX)) {
                    dexFileNameList.add(file.getName());
                }
            }
        }

    }

    private String parseResourceId(String resId) {
        if (!Util.isNullOrNil(resId) && resId.startsWith("0x")) {
            if (resId.length() == 10) {
                return resId;

View on GitHub (pinned to 3b8293bd65)