Tencent/matrix · error · TaskInitException

---resguard mapping file <config.getResMappingFilePath()>…

Error message

---resguard mapping file <config.getResMappingFilePath()> is not legal!

What it means

UnzipTask.init() validates the optional resource-guard (resguard) mapping file: if config.getResMappingFilePath() is set, FileUtil.isLegalFile must pass, otherwise TaskInitException is thrown with the configured path in the message. This mapping maps obfuscated resource names back to originals.

Solutions

  1. Verify the configured resguard mapping file exists and is readable, and update the path.
  2. Regenerate the resguard mapping from the same build that produced the APK being analyzed.
  3. Omit resMappingFilePath if the APK was not processed by resguard.

Example fix

// before
config.setResMappingFilePath("resguard-mapping.txt"); // missing
// after
File rm = new File("build/resguard/mapping.txt");
if (rm.isFile()) config.setResMappingFilePath(rm.getAbsolutePath());
Defensive patterns

Strategy: validation

Validate before calling

String p = config.getResMappingFilePath();
if (p != null && !p.isEmpty()) {
    File f = new File(p);
    if (!f.isFile() || !f.canRead()) {
        throw new IllegalArgumentException("resguard mapping not readable: " + p);
    }
}

Try / catch

try {
    task.init();
} catch (TaskInitException e) {
    if (e.getMessage().contains("resguard mapping")) {
        config.setResMappingFilePath(null); // proceed without resguard decoding
    } else throw e;
}

Prevention

When it happens

Trigger: Setting a non-empty resMappingFilePath that points to a missing, unreadable, or directory path (e.g. a resguard mapping from a previous build).

Common situations: Using WeChat resguard builds where the resource mapping file was regenerated/moved; stale path after clean; pointing to the resguard mapping of a different APK.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

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

            throw new TaskInitException(TAG + "---'" + config.getApkPath() + "' is not exist!");
        }
        if (Util.isNullOrNil(config.getUnzipPath())) {
            throw new TaskInitException(TAG + "---APK-UNZIP-PATH can not be null!");
        }
        Log.i(TAG, "outputPath:%s", config.getUnzipPath());
        outputFile = new File(config.getUnzipPath());

        if (!Util.isNullOrNil(config.getMappingFilePath())) {
            mappingTxt = new File(config.getMappingFilePath());
            if (!FileUtil.isLegalFile(mappingTxt)) {
                throw new TaskInitException(TAG + "---mapping file " + config.getMappingFilePath() + " is not legal!");
            }
        }

        if (!Util.isNullOrNil(config.getResMappingFilePath())) {
            resMappingTxt = new File(config.getResMappingFilePath());
            if (!FileUtil.isLegalFile(resMappingTxt)) {
                throw new TaskInitException(TAG + "---resguard mapping file " + config.getResMappingFilePath() + " is not legal!");
            }
        }
    }

    private void readMappingTxtFile() throws IOException {
        if (mappingTxt != null) {
            BufferedReader bufferedReader = new BufferedReader(new FileReader(mappingTxt));
            String line = bufferedReader.readLine();
            String beforeClass = "", afterClass = "";
            try {
                while (line != null) {
                    if (!line.startsWith(" ")) {
                        String[] pair = line.split("->");
                        if (pair.length == 2) {
                            beforeClass = pair[0].trim();
                            afterClass = pair[1].trim();
                            afterClass = afterClass.substring(0, afterClass.length() - 1);
                            if (!Util.isNullOrNil(beforeClass) && !Util.isNullOrNil(afterClass)) {

View on GitHub (pinned to 3b8293bd65)