quarkusio/quarkus · error · IllegalArgumentException

Failed to translate <url> to local path

Error message

Failed to translate <url> to local path

What it means

toLocalPath converts a file: URL to a java.nio.file.Path via Paths.get(url.toURI()). If the URL cannot be represented as a valid URI (illegal characters, unencoded spaces, opaque URIs), URISyntaxException is wrapped in IllegalArgumentException('Failed to translate <url> to local path').

Source

Thrown at independent-projects/tools/devtools-common/src/main/java/io/quarkus/platform/descriptor/loader/json/ResourceLoaders.java:84

                }
                return function.apply(localPath);
            } catch (IOException e) {
                throw new UncheckedIOException("Failed to read " + jar, e);
            }
        }

        if (FILE.equals(url.getProtocol())) {
            return function.apply(toLocalPath(url));
        }

        throw new IllegalArgumentException("Unexpected protocol " + url.getProtocol() + " for URL " + url);
    }

    private static Path toLocalPath(final URL url) {
        try {
            return Paths.get(url.toURI());
        } catch (URISyntaxException e) {
            throw new IllegalArgumentException("Failed to translate " + url + " to local path", e);
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Construct the URL via File.toURI() or Path.toUri() instead of string concatenation so special characters are encoded
2. Rename/relocate the offending directory to a path without spaces or special characters
3. Pre-encode the path portion with URLEncoder/URI multi-arg constructor

Example fix

// before
URL url = new URL("file:" + somePath); // breaks on spaces
// after
URL url = new File(somePath).toURI().toURL();

static boolean uriSafe(URL url) {
    try { url.toURI(); return true; } catch (URISyntaxException e) { return false; }
}

static boolean isEncodableFileUrl(URL url) {
    return "file".equals(url.getProtocol()) && !url.getPath().matches(".*[ #\\\\].*") || uriSafe(url);
}

try {
    return ResourceLoaders.processAsPath(url, fn);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Failed to translate")) {
        URL fixed = Paths.get(url.getPath()).toUri().toURL(); // re-encode
        return ResourceLoaders.processAsPath(fixed, fn);
    }
    throw e;
}

When it happens

Trigger: Calling processAsPath/loadResourceAsPath with a file: URL containing characters illegal in a URI (spaces, '#', non-ASCII) that were not percent-encoded, or an opaque URL like file:rel/path.

Common situations: Project paths with spaces or unicode characters on Windows/macOS; URLs built via string concatenation ('file:' + path) instead of new File(path).toURI(); IDE-launched tools receiving unencoded paths.

Related errors

• Failed to translate
• Unable to create protection domain for ${jarPath}
• path is null
• Failed to create URI
• failed to create URI

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