junit-team/junit5 · error · PreconditionViolationException

Failed to retrieve canonical path for file

Error message

Failed to retrieve canonical path for file: ${file}

What it means

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.

Solutions

1. Verify read+execute permission on all parent directories of the file: the JVM must traverse them to canonicalize.
2. Remove or fix broken symlinks in the path.
3. If you already know the canonical absolute path, prefer selectFile(String) (the string overload) to bypass getCanonicalPath().
4. Move/copy the file to a location with clean path resolution and retry.

Example fix

// before
FileSelector s = selectFile(new File("/sym/link/to/test.txt"), position); // symlink broken
// after
FileSelector s = selectFile(new File("/real/path/to/test.txt").getAbsoluteFile(), position);
// or use the String overload with a known absolute path
FileSelector s = selectFile("/real/path/to/test.txt", position);

// Pre-validate that canonicalization will succeed.
import java.io.File;
File f = userFile;
if (!f.isFile()) throw new IllegalArgumentException("Not an existing file: " + f);
try { f.getCanonicalPath(); } catch (IOException e) {
  throw new IllegalArgumentException("Cannot canonicalize " + f + ": " + e.getMessage(), e);
}
// If that fails, prefer selectFile(canonicalAbsolutePathString) instead.

try { return selectFile(file, position); } catch (PreconditionViolationException e) { /* fall back to String overload */ return selectFile(file.getAbsolutePath(), position); }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Failed to retrieve canonical path for directory
• Could not find any resource(s) with name
• Failed to create a java.net.URI from
• Failed to retrieve canonical path for directory
• Failed to retrieve canonical path for file

AI-assisted analysis of junit-team/junit5@f070c699a0 (2026-08-11). Data as JSON: /api/errors/4f4cffff0adfb69e. Report an issue: GitHub.

Appendix: source

Thrown at junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/DiscoverySelectors.java:187

	 *
	 * @param file the file to select; never {@code null}
	 * @param position the position inside the file; may be {@code null}
	 * @see FileSelector
	 * @see #selectFile(File)
	 * @see #selectFile(String)
	 * @see #selectFile(String, FilePosition)
	 * @see #selectDirectory(String)
	 * @see #selectDirectory(File)
	 */
	public static FileSelector selectFile(File file, @Nullable FilePosition position) {
		Preconditions.notNull(file, "File must not be null");
		Preconditions.condition(file.isFile(),
			() -> "The supplied java.io.File [%s] must represent an existing file".formatted(file));
		try {
			return new FileSelector(file.getCanonicalPath(), position);
		}
		catch (IOException ex) {
			throw new PreconditionViolationException("Failed to retrieve canonical path for file: " + file, ex);
		}
	}

	/**
	 * Create a {@code DirectorySelector} for the supplied directory path.
	 *
	 * <p>This method selects the directory using the supplied path <em>as is</em>,
	 * without verifying if the directory exists.
	 *
	 * @param path the path to the directory to select; never {@code null} or blank
	 * @see DirectorySelector
	 * @see #selectDirectory(File)
	 * @see #selectFile(String)
	 * @see #selectFile(File)
	 */
	public static DirectorySelector selectDirectory(String path) {
		Preconditions.notBlank(path, "Directory path must not be null or blank");
		return new DirectorySelector(path);

View on GitHub (pinned to f070c699a0)