quarkusio/quarkus · error · IllegalArgumentException

Unable to validate remote-dev path: <file>

Error message

Unable to validate remote-dev path: <file>

What it means

While walking path components, calling toRealPath() on an existing component can itself throw IOException; the validation wraps this in an IllegalArgumentException with this message (cause attached). The server could not determine whether the path stays inside the root, so it fails closed.

Source

Thrown at core/deployment/src/main/java/io/quarkus/deployment/dev/RuntimeUpdatesProcessor.java:490

        final Path realRoot;
        try {
            realRoot = normalizedRoot.toRealPath();
        } catch (IOException e) {
            throw new IllegalArgumentException("Unable to validate the application root for remote-dev path: " + file, e);
        }
        Path current = normalizedRoot;
        for (Path element : normalizedRoot.relativize(resolved)) {
            current = current.resolve(element);
            if (Files.isSymbolicLink(current)) {
                throw new IllegalArgumentException("Symbolic links are not allowed in remote-dev paths: " + file);
            }
            if (Files.exists(current, LinkOption.NOFOLLOW_LINKS)) {
                try {
                    if (!current.toRealPath().startsWith(realRoot)) {
                        throw new IllegalArgumentException("Path leaves the application root: " + file);
                    }
                } catch (IOException e) {
                    throw new IllegalArgumentException("Unable to validate remote-dev path: " + file, e);
                }
            } else {
                break;
            }
        }
    }

    private static String normalizeFile(String file) {
        requireNonNull(file, "file");
        file = file.replace('\\', '/');
        if (file.startsWith("/")) {
            file = file.substring(1);
        }
        return file;
    }

    @Override
    public boolean isTest() {

View on GitHub (pinned to e1c734241f)

Solutions

  1. Fix permissions on the intermediate directories of the path (chmod a+rx on parents).
  2. Re-run the sync after the filesystem stabilizes (avoid mvn clean during remote-dev sync).
  3. Check the health of the network filesystem backing the root.
  4. Restart the dev server if the root layout changed underneath it.

Example fix

// before: parent dir mode 0700 owned by other user -> toRealPath() throws
// after (server shell): chmod a+rx /path/to/parent
Defensive patterns

Strategy: validation

Validate before calling

Path root = Path.of(".").toAbsolutePath().normalize();
for (Path p = root; p != null; p = p.getParent()) {
    if (!Files.isReadable(p) || !Files.isExecutable(p))
        throw new IllegalStateException("cannot traverse: " + p);
    if (p.equals(root.getRoot())) break;
}

Try / catch

try {
    client.sync(path);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unable to validate remote-dev path")) {
        Throwable cause = e.getCause();
        log.errorf("Path validation IO failure (%s) — check permissions/storage, then retry", cause == null ? "?" : cause.getMessage());
    } else throw e;
}

Prevention

When it happens

Trigger: updateFile or resolveApplicationPath validating a path where current.toRealPath() throws IOException for an existing component — permission denied on a parent, I/O error, or racing deletion of the component during traversal.

Common situations: Permission changes on intermediate directories; concurrent mvn clean removing components mid-validation; flaky network filesystems.

Related errors

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