{"record":{"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":"validation","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/f070c699a08b5d8393df9afd147af5c5e90bb21b/junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/DiscoverySelectors.java#L169-L205","documentation":"DiscoverySelectors.selectFile(File, position) validates the File is non-null and isFile(), then calls file.getCanonicalPath(). If the canonical path cannot be resolved (IOException — e.g. a path component is unreadable due to permissions, or filesystem-level failure), a PreconditionViolationException wraps it.","triggerScenarios":"Calling selectFile(file, pos) on a path where File.getCanonicalPath() throws: permission denied on a parent directory, a broken symlink, an OS/filesystem error resolving the absolute path, or (rarely) a non-existent intermediate. Note existence as a regular file is already checked.","commonSituations":"Restricted directories (the process can stat the file but not resolve the canonical path through parents); symlink loops; NFS-mounted paths with intermittent resolver failures; running in a container with a restricted view of the filesystem.","solutions":["Verify read+execute permission on all parent directories of the file: the JVM must traverse them to canonicalize.","Remove or fix broken symlinks in the path.","If you already know the canonical absolute path, prefer selectFile(String) (the string overload) to bypass getCanonicalPath().","Move/copy the file to a location with clean path resolution and retry."],"exampleFix":"// before\nFileSelector s = selectFile(new File(\"/sym/link/to/test.txt\"), position); // symlink broken\n// after\nFileSelector s = selectFile(new File(\"/real/path/to/test.txt\").getAbsoluteFile(), position);\n// or use the String overload with a known absolute path\nFileSelector s = selectFile(\"/real/path/to/test.txt\", position);","handlingStrategy":"validation","validationCode":"// Pre-validate that canonicalization will succeed.\nimport java.io.File;\nFile f = userFile;\nif (!f.isFile()) throw new IllegalArgumentException(\"Not an existing file: \" + f);\ntry { f.getCanonicalPath(); } catch (IOException e) {\n  throw new IllegalArgumentException(\"Cannot canonicalize \" + f + \": \" + e.getMessage(), e);\n}\n// If that fails, prefer selectFile(canonicalAbsolutePathString) instead.\n","typeGuard":null,"tryCatchPattern":"try { return selectFile(file, position); } catch (PreconditionViolationException e) { /* fall back to String overload */ return selectFile(file.getAbsolutePath(), position); }","preventionTips":["Ensure the test JVM can read+traverse all parent directories of the file.","Prefer selectFile(String) with a known absolute canonical path when canonicalization is at risk.","Avoid broken symlinks in the path chain."],"tags":["discovery","file-selector","filesystem","engine"],"backgroundTag":null,"analyzedSha":"f070c699a08b5d8393df9afd147af5c5e90bb21b","analyzedAt":"2026-08-11T20:31:00.530Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}