junit-team/junit5 · error · JUnitException

Failed to retrieve canonical path for file

Error message

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

What it means

FileSource(File, position) constructor canonicalizes the File via getCanonicalFile(); an IOException is wrapped as JUnitException. FileSource is the engine's test source descriptor for a class/resource file. Symmetric to DirectorySource (118) but for files; the constructor is private so this fires via FileSource.from(...) which delegates here.

Solutions

1. Ensure all parent directories are readable and traversable by the test JVM.
2. Pre-canonicalize the File where you can handle the IOException, then pass the resolved File to FileSource.from().
3. Resolve symlinks before discovery so the engine receives a clean canonical path.
4. Reconfigure the build tool to supply canonical absolute file paths.

Example fix

// before
FileSource src = FileSource.from(new File("/links/MyClass.java"));
// after
File canonical = new File("/links/MyClass.java").getCanonicalFile();
FileSource src = FileSource.from(canonical);

// Pre-canonicalize the file before the engine constructs the FileSource.
import java.io.File;
File f = userFile;
if (!f.isFile()) throw new IllegalArgumentException("Not a file: " + f);
File canonical;
try { canonical = f.getCanonicalFile(); } catch (IOException e) {
  throw new IllegalArgumentException("Cannot canonicalize " + f + ": " + e.getMessage(), e);
}
FileSource src = FileSource.from(canonical);

try { return FileSource.from(file); } catch (org.junit.platform.commons.JUnitException e) { /* pre-canonicalize and retry, or report */ throw e; }

When it happens

Trigger: Building a FileSource for a File whose canonical path resolution fails: broken symlink chain, unreadable parent directory, or an OS/filesystem resolution error. Occurs when the engine constructs a source descriptor for a discovered file.

Common situations: Discovered source file behind a symlink loop or restricted directory; IDE/build passing a path that the test JVM resolves differently; network-mounted filesystem intermittent canonicalization failures.

Related errors

• Failed to retrieve canonical path for directory
• Failed to retrieve canonical path for directory
• Failed to retrieve canonical path for file
• Could not find any resource(s) with name
• Could not open color palette properties file

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

Appendix: source

Thrown at junit-platform-engine/src/main/java/org/junit/platform/engine/support/descriptor/FileSource.java:77

	public static FileSource from(File file, @Nullable FilePosition filePosition) {
		return new FileSource(file, filePosition);
	}

	private final File file;

	private final @Nullable FilePosition filePosition;

	private FileSource(File file) {
		this(file, null);
	}

	private FileSource(File file, @Nullable FilePosition filePosition) {
		Preconditions.notNull(file, "file must not be null");
		try {
			this.file = file.getCanonicalFile();
		}
		catch (IOException ex) {
			throw new JUnitException("Failed to retrieve canonical path for file: " + file, ex);
		}
		this.filePosition = filePosition;
	}

	private FileSource(FileSource fileSource, @Nullable FilePosition filePosition) {
		this.file = fileSource.file;
		this.filePosition = filePosition;
	}

	/**
	 * Get the {@link URI} for the source {@linkplain #getFile file}.
	 *
	 * @return the source {@code URI}; never {@code null}
	 */
	@Override
	public URI getUri() {
		return getFile().toURI();
	}

View on GitHub (pinned to f070c699a0)