quarkusio/quarkus · error · java.lang.IllegalArgumentException

'..' cannot be used in resource paths, but got

Error message

'..' cannot be used in resource paths, but got

What it means

PathTree resource lookup rejects resource paths containing '..' path segments. This is a security/integrity check in ensureResourcePath to disallow reading files outside the path tree root via path traversal. Any resource name that resolves to a literal '..' element is refused before the tree is walked.

Source

Thrown at independent-projects/bootstrap/app-model/src/main/java/io/quarkus/paths/PathTreeVisit.java:44

    }

    static boolean isAbsolutePath(String path) {
        return path != null && !path.isEmpty()
                && (path.charAt(0) == '/' // we want to check for '/' on every OS
                        || USE_WINDOWS_ABSOLUTE_PATH_PATTERN
                                && (windowsAbsolutePathPattern().matcher(path).matches())
                        || path.startsWith(FileSystems.getDefault().getSeparator()));
    }

    static void ensureResourcePath(FileSystem fs, String path) {
        if (isAbsolutePath(path)) {
            throw new IllegalArgumentException("Expected a path relative to the root of the path tree but got " + path);
        }
        // this is to disallow reading outside the path tree root
        if (path != null && path.contains("..")) {
            for (Path pathElement : fs.getPath(path)) {
                if (pathElement.toString().equals("..")) {
                    throw new IllegalArgumentException("'..' cannot be used in resource paths, but got " + path);
                }
            }
        }
    }

    static String resourceNameToFsPath(String resourceName, FileSystem fs) {
        return fs.getSeparator().equals("/") ? resourceName : resourceName.replace("/", fs.getSeparator());
    }

    static void walk(Path root, Path rootDir, Path walkDir, PathFilter pathFilter, Map<String, String> multiReleaseMapping,
            PathVisitor visitor) {
        final PathTreeVisit visit = new PathTreeVisit(root, rootDir, pathFilter, multiReleaseMapping);
        try (Stream<Path> files = Files.walk(walkDir)) {
            final Iterator<Path> i = files.iterator();
            while (i.hasNext()) {
                if (!visit.setCurrent(i.next())) {
                    continue;
                }

View on GitHub (pinned to e1c734241f)

Solutions

  1. Remove or normalize '..' segments from the resource path before passing it (e.g. Path.normalize() then verify it does not start with '/' and contains no '..')
  2. Verify the resource name is a classpath-relative name like 'com/foo/Bar.class', not a filesystem path
  3. If the intent is to reach an absolute/external file, do not go through the path tree; open the file directly

Example fix

// before
String path = base + "/../" + resource;
tree.apply(path, visitor);
// after
String path = Path.of(base, resource).normalize().toString();
if (path.contains("..")) { throw new IllegalArgumentException("bad path"); }
tree.apply(path, visitor);
Defensive patterns

Strategy: validation

Validate before calling

if (resourcePath == null || resourcePath.startsWith("/") || resourcePath.contains("..")) { throw new IllegalArgumentException("Invalid resource path: " + resourcePath); }

Type guard

boolean isValidResourcePath(String p) { return p != null && !p.startsWith("/") && !p.contains(".."); }

Try / catch

try { tree.apply(path, visitor); } catch (IllegalArgumentException e) { if (e.getMessage().contains("'..'") || e.getMessage().startsWith("Expected a path relative")) { log.warn("Rejected resource path: " + path); } else { throw e; } }

Prevention

When it happens

Trigger: Calling a PathTree open/getResource/apply visitor API (e.g. via PathTreeUtils or CuratedApplication) with a resource name like 'foo/../../secret' or 'a/../b' where '..' survives as a path element after splitting.

Common situations: Resource names built by string concatenation from config properties or user input; normalized-relative paths that still contain '..' segments; classpath scanning code passing relative filesystem paths instead of resource names.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/f083673d38d2859e. Report an issue: GitHub.