{"record":{"id":"0787c183a4162394","repo":"Tencent/matrix","slug":"can-t-read-mapping-file","errorCode":null,"errorMessage":"Can't read mapping file","messagePattern":"Can't read mapping file","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"matrix/matrix-android/matrix-gradle-plugin/src/main/java/com/tencent/matrix/trace/retrace/MappingReader.java","lineNumber":70,"sourceCode":"            while (true) {\n                String line = reader.readLine();\n                if (line == null) {\n                    break;\n                }\n                line = line.trim();\n                if (!line.startsWith(\"#\")) {\n                    // a class mapping\n                    if (line.endsWith(SPLIT)) {\n                        className = parseClassMapping(line, mappingProcessor);\n                    } else if (className != null) { // a class member mapping\n                        parseClassMemberMapping(className, line, mappingProcessor);\n                    }\n                } else {\n                    Log.i(TAG, \"comment:# %s\", line);\n                }\n            }\n        } catch (IOException err) {\n            throw new IOException(\"Can't read mapping file\", err);\n        } finally {\n            try {\n                reader.close();\n            } catch (IOException ex) {\n                // do nothing\n            }\n        }\n    }\n\n    /**\n     * @param line read content\n     * @param mappingProcessor\n     * @return\n     */\n    private String parseClassMapping(String line, MappingProcessor mappingProcessor) {\n\n        int leftIndex = line.indexOf(ARROW);\n        if (leftIndex < 0) {","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/Tencent/matrix/blob/3b8293bd65d47eeea7caf1f32a3a5d4d5eab60e7/matrix/matrix-android/matrix-gradle-plugin/src/main/java/com/tencent/matrix/trace/retrace/MappingReader.java#L52-L88","documentation":"MappingReader.read() parses a ProGuard/R8 mapping.txt file line by line to enable stack-trace retrace. Any IOException encountered while reading the file (including from the wrapped BufferedReader) is caught and rethrown as a new IOException with the message \"Can't read mapping file\", preserving the original cause. This tells you the mapping file itself could not be read, not that its content was semantically wrong.","triggerScenarios":"Calling MappingReader.read() (typically from run()) when the mapping file path does not exist, is unreadable due to permissions, is already closed/corrupt, or the underlying stream hits an I/O error mid-parse (disk error, interrupted stream).","commonSituations":"Build/CI pipelines that pass a missing or stale mapping.txt path after a clean; retrace tools pointed at a renamed obfuscation output directory; reading the mapping from storage the process lacks permission for; transient disk or file-descriptor issues.","solutions":["Check the underlying cause (err.getCause()) to see whether it is FileNotFoundException, permission denied, or another I/O failure.","Verify the mapping file path passed to MappingReader exists and is a readable regular file before calling read().","Ensure the file is not opened twice / not closed by another component before read() runs.","In CI, confirm the mapping.txt artifact from the ProGuard/R8 task is produced and copied to the expected location."],"exampleFix":"// before\nMappingReader reader = new MappingReader(new File(mappingPath));\nreader.read(sink);\n// after\nFile f = new File(mappingPath);\nif (!f.isFile() || !f.canRead()) {\n    throw new IllegalStateException(\"mapping file missing or unreadable: \" + mappingPath);\n}\ntry {\n    new MappingReader(f).read(sink);\n} catch (IOException e) {\n    e.printStackTrace(); // inspect getCause() for the real reason\n}","handlingStrategy":"try-catch","validationCode":"File f = new File(mappingPath);\nif (f == null || !f.isFile() || !f.canRead() || f.length() == 0) {\n    throw new IllegalStateException(\"mapping file missing/unreadable: \" + mappingPath);\n}","typeGuard":null,"tryCatchPattern":"try {\n    new MappingReader(mappingFile).read(sink);\n} catch (IOException e) {\n    Throwable cause = e.getCause();\n    if (cause instanceof FileNotFoundException) {\n        // fix path / regenerate mapping\n    }\n    log.warn(\"retrace skipped: mapping unreadable\", e);\n}","preventionTips":["Always verify the mapping file exists and is readable before retrace.","In CI, fail fast if the ProGuard/R8 mapping artifact is missing after a build.","Log e.getCause() to distinguish missing file vs permissions vs mid-read I/O errors."],"tags":["io","mapping-file","proguard","retrace"],"backgroundTag":"file-read-failed","analyzedSha":"3b8293bd65d47eeea7caf1f32a3a5d4d5eab60e7","analyzedAt":"2026-09-08T08:01:39.722Z","contentChangedAt":"2026-09-08T08:01:39.722Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}