Tencent/matrix · error · TaskInitException

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

Error message

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

What it means

UnzipTask.init() validates the optional ProGuard mapping file: if config.getMappingFilePath() is set, the file must exist and be a regular, readable file (FileUtil.isLegalFile). Otherwise TaskInitException is thrown with the configured path in the message (shown as <config.getMappingFilePath()>).

Solutions

  1. Check the path in the message exists and is a regular readable file (not a directory).
  2. Point mappingFilePath at the fresh mapping.txt from the same release build (e.g. app/build/outputs/mapping/release/mapping.txt).
  3. If you don't need ProGuard mapping analysis, leave mappingFilePath unset (null) rather than passing a bad path.

Example fix

// before
config.setMappingFilePath("old/path/mapping.txt"); // stale
// after
File mapping = new File("app/build/outputs/mapping/release/mapping.txt");
if (mapping.isFile()) config.setMappingFilePath(mapping.getAbsolutePath());
Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try {
    task.init();
} catch (TaskInitException e) {
    if (e.getMessage().contains("mapping file")) {
        logger.warn("Skipping mapping validation, bad mapping path");
        config.setMappingFilePath(null); // or fix path and retry
    } else throw e;
}

Prevention

When it happens

Trigger: Setting a non-null/non-empty mappingFilePath that points to a missing, deleted, or directory path instead of a legal mapping txt file.

Common situations: Stale path after a clean build removed mapping.txt; pointing at the wrong module's mapping; path given but app was not built with minification so mapping.txt was never produced.

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/1c740078861393c4. 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:99

        super.init();
        if (Util.isNullOrNil(config.getApkPath())) {
            throw new TaskInitException(TAG + "---APK-FILE-PATH can not be null!");
        }
        Log.i(TAG, "inputPath:%s", config.getApkPath());
        inputFile = new File(config.getApkPath());
        if (!inputFile.exists()) {
            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) {

View on GitHub (pinned to 3b8293bd65)