{"record":{"id":"176a62bc970b5573","repo":"junit-team/junit5","slug":"failed-to-read-contents-of-reference","errorCode":null,"errorMessage":"Failed to read contents of ${reference}.","messagePattern":"Failed to read contents of (.+?)\\.","errorType":"exception","errorClass":"JUnitException","httpStatus":null,"severity":"error","filePath":"junit-platform-commons/src/main/java/org/junit/platform/commons/util/ModuleUtils.java","lineNumber":269,"sourceCode":"\t\t * Scan module reference for classes that potentially contain testable methods.\n\t\t */\n\t\tList<Class<?>> scan(ModuleReference reference) {\n\t\t\ttry (ModuleReader reader = reference.open()) {\n\t\t\t\ttry (Stream<String> names = reader.list()) {\n\t\t\t\t\t// @formatter:off\n\t\t\t\t\treturn names.filter(name -> !name.endsWith(\"/\")) // remove directories\n\t\t\t\t\t\t\t.map(Path::of)\n\t\t\t\t\t\t\t.filter(SearchPathUtils::isClassOrSourceFile)\n\t\t\t\t\t\t\t.map(SearchPathUtils::determineFullyQualifiedClassName)\n\t\t\t\t\t\t\t.filter(classFilter::match)\n\t\t\t\t\t\t\t.<Class<?>> map(this::loadClassUnchecked)\n\t\t\t\t\t\t\t.filter(classFilter::match)\n\t\t\t\t\t\t\t.toList();\n\t\t\t\t\t// @formatter:on\n\t\t\t\t}\n\t\t\t}\n\t\t\tcatch (IOException e) {\n\t\t\t\tthrow new JUnitException(\"Failed to read contents of \" + reference + \".\", e);\n\t\t\t}\n\t\t}\n\n\t\t/**\n\t\t * Load class by its binary name.\n\t\t *\n\t\t * @see ClassLoader#loadClass(String)\n\t\t */\n\t\tprivate Class<?> loadClassUnchecked(String binaryName) {\n\t\t\ttry {\n\t\t\t\treturn classLoader.loadClass(binaryName);\n\t\t\t}\n\t\t\tcatch (ClassNotFoundException e) {\n\t\t\t\tthrow new JUnitException(\"Failed to load class with name '\" + binaryName + \"'.\", e);\n\t\t\t}\n\t\t}\n\n\t}","sourceCodeStart":251,"sourceCodeEnd":287,"githubUrl":"https://github.com/junit-team/junit5/blob/f070c699a08b5d8393df9afd147af5c5e90bb21b/junit-platform-commons/src/main/java/org/junit/platform/commons/util/ModuleUtils.java#L251-L287","documentation":"JUnitException thrown by ModuleReferenceClassScanner.scan when ModuleReader.open() or reader.list() raises IOException while scanning a JPMS module for classes. The offending ModuleReference is in the message and the IOException is the cause.","triggerScenarios":"JPMS module classpath scanning where reading the module's contents fails - corrupt modular jar, broken module-path entry, IO error, or permission denial on the module artifact.","commonSituations":"Running tests on the module path (--module-path) with a corrupt or unreadable module; modular jar built incorrectly; module path pointing at a network resource that drops mid-scan.","solutions":["Verify the module artifact opens cleanly: `jar tf <module>.jar` or `unzip -l`","Rebuild the offending modular jar","Check module-path permissions and storage reliability","Move the artifact to local disk if scanning a remote mount"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    // module classpath scanning\n} catch (JUnitException e) {\n    if (e.getCause() instanceof IOException io) {\n        // inspect the module reference, repair the module path\n    }\n}","preventionTips":["Validate modular jars in CI before test runs","Prefer local, reliable storage for the module path","Pin module-path entries explicitly rather than using broad globs"],"tags":["classpath-scanning","jpms","module","io"],"backgroundTag":null,"analyzedSha":"f070c699a08b5d8393df9afd147af5c5e90bb21b","analyzedAt":"2026-08-11T20:31:00.530Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}