{"id":"4f4cffff0adfb69e","repo":"junit-team/junit5","slug":"failed-to-retrieve-canonical-path-for-file-file","errorCode":null,"errorMessage":"Failed to retrieve canonical path for file: ${file}","messagePattern":"Failed to retrieve canonical path for file: (.+?)","errorType":"exception","errorClass":"PreconditionViolationException","httpStatus":null,"severity":"error","filePath":"junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/DiscoverySelectors.java","lineNumber":187,"sourceCode":"\t *\n\t * @param file the file to select; never {@code null}\n\t * @param position the position inside the file; may be {@code null}\n\t * @see FileSelector\n\t * @see #selectFile(File)\n\t * @see #selectFile(String)\n\t * @see #selectFile(String, FilePosition)\n\t * @see #selectDirectory(String)\n\t * @see #selectDirectory(File)\n\t */\n\tpublic static FileSelector selectFile(File file, @Nullable FilePosition position) {\n\t\tPreconditions.notNull(file, \"File must not be null\");\n\t\tPreconditions.condition(file.isFile(),\n\t\t\t() -> \"The supplied java.io.File [%s] must represent an existing file\".formatted(file));\n\t\ttry {\n\t\t\treturn new FileSelector(file.getCanonicalPath(), position);\n\t\t}\n\t\tcatch (IOException ex) {\n\t\t\tthrow new PreconditionViolationException(\"Failed to retrieve canonical path for file: \" + file, ex);\n\t\t}\n\t}\n\n\t/**\n\t * Create a {@code DirectorySelector} for the supplied directory path.\n\t *\n\t * <p>This method selects the directory using the supplied path <em>as is</em>,\n\t * without verifying if the directory exists.\n\t *\n\t * @param path the path to the directory to select; never {@code null} or blank\n\t * @see DirectorySelector\n\t * @see #selectDirectory(File)\n\t * @see #selectFile(String)\n\t * @see #selectFile(File)\n\t */\n\tpublic static DirectorySelector selectDirectory(String path) {\n\t\tPreconditions.notBlank(path, \"Directory path must not be null or blank\");\n\t\treturn new DirectorySelector(path);","sourceCodeStart":169,"sourceCodeEnd":205,"githubUrl":"https://github.com/junit-team/junit5/blob/956246301e03d757539f7b76dd5a91f298637563/junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/DiscoverySelectors.java#L169-L205","documentation":"Thrown by DiscoverySelectors.selectFile(File, FilePosition) at line 183-188 when file.getCanonicalPath() raises IOException. selectFile(File) requires the path to be an existing regular file (Preconditions.condition at line 181) before this point, so the canonical resolution fails on a file that does exist but whose canonical form cannot be computed.","triggerScenarios":"Calling selectFile(file) where 'file' passes isFile() but the filesystem cannot resolve its canonical path (broken symlinks in a loop, removed parent directory, I/O error reading the filesystem metadata, or a path on a failing/unmounted network filesystem).","commonSituations":"Symlink chains that became invalid between isFile() and getCanonicalPath(); files on NFS/SMB shares that dropped; containers where the underlying mount was removed; very deep paths hitting OS limits; security managers denying canonical-path resolution.","solutions":["Check file.getCanonicalFile() yourself first and handle IOException before building the selector.","Resolve the canonical path via java.nio.file.Path.toRealPath() which gives clearer errors, then build the File from it.","Avoid selecting through symlinks; canonicalize the target path once and store the resolved form.","Ensure the underlying filesystem/mount is healthy and accessible at selection time."],"exampleFix":"// before\nvar selector = DiscoverySelectors.selectFile(new File(path)); // throws on broken symlink\n\n// after\nFile canonical = Path.of(path).toRealPath().toFile();\nvar selector = DiscoverySelectors.selectFile(canonical.getCanonicalPath()); // String overload, no re-resolution","handlingStrategy":"validation","validationCode":"File f = new File(path);\nif (!f.isFile()) throw new IllegalArgumentException(\"not a file: \" + f);\nFile canonical = Path.of(path).toRealPath().toFile(); // throws a clearer exception on failure\nvar selector = DiscoverySelectors.selectFile(canonical.getCanonicalPath()); // String overload","typeGuard":null,"tryCatchPattern":"try {\n    return DiscoverySelectors.selectFile(file);\n} catch (PreconditionViolationException e) {\n    throw new IllegalStateException(\"cannot canonicalize file: \" + file, e.getCause());\n}","preventionTips":["Resolve canonical paths once with Path.toRealPath() and reuse the String form.","Avoid selecting files through volatile symlinks.","Use selectFile(String) to avoid re-resolution at selection time."],"tags":["junit-platform","discovery","io","filesystem","file-selector","canonical-path"],"analyzedSha":"956246301e03d757539f7b76dd5a91f298637563","analyzedAt":"2026-08-04T19:25:17.049Z","schemaVersion":2}