junit-team/junit5 · error · JUnitException

Failed to retrieve canonical path for directory: ${directory

Error message

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

What it means

Thrown by the DirectorySource constructor (line 49-57) when directory.getCanonicalFile() raises IOException, wrapped in a JUnitException. DirectorySource.from(File) is used to attach a directory as a TestSource on a TestDescriptor. Unlike the discovery selectors, this path does not pre-check existence.

Source

Thrown at junit-platform-engine/src/main/java/org/junit/platform/engine/support/descriptor/DirectorySource.java:55

	/**
	 * Create a new {@code DirectorySource} using the supplied
	 * {@linkplain File directory}.
	 *
	 * @param directory the source directory; must not be {@code null}
	 */
	public static DirectorySource from(File directory) {
		return new DirectorySource(directory);
	}

	private final File directory;

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

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

	/**
	 * Get the source {@linkplain File directory}.
	 *
	 * @return the source directory; never {@code null}
	 */

View on GitHub (pinned to 956246301e)

Solutions

1. Resolve the canonical File yourself (Path.toRealPath().toFile()) before calling DirectorySource.from(...).
2. Guard with Files.isDirectory(Path) and Files.isReadable before constructing the source.
3. Avoid holding long-lived File references to volatile locations; re-resolve at descriptor-creation time.
4. Surface the caused-by IOException to diagnose the underlying OS/filesystem error.

Example fix

// before
TestSource source = DirectorySource.from(new File(dirPath)); // throws JUnitException

// after
File canonical = Path.of(dirPath).toRealPath().toFile();
TestSource source = DirectorySource.from(canonical);

File canonical = Path.of(dirPath).toRealPath().toFile(); // clearer error
TestSource source = DirectorySource.from(canonical);

try {
    return DirectorySource.from(dir);
} catch (JUnitException e) {
    throw new IllegalStateException("cannot build DirectorySource for " + dir, e.getCause());
}

When it happens

Trigger: Calling DirectorySource.from(file) for a directory whose canonical form cannot be resolved (broken symlink chain, removed parent, I/O fault on the filesystem, or an unreachable network mount). Common inside custom engines or extensions that build TestDescriptors for filesystem locations.

Common situations: Custom TestEngine/extension creating a TestSource for a directory that later becomes invalid; descriptor created from a stale File reference after the filesystem changed; module-path or container environments with non-standard filesystems.

Related errors

• Failed to retrieve canonical path for file: ${file}
• Failed to retrieve canonical path for file: ${file}
• Failed to retrieve canonical path for directory: ${directory
• Could not open color palette properties file
• Failed to create output dir

AI-assisted analysis of junit-team/junit5@956246301e (2026-08-04). Data as JSON: /data/errors/a47de9a3591af2a8.json. Report an issue: GitHub.