{"record":{"id":"477aecd72c9efdd4","repo":"quarkusio/quarkus","slug":"failed-to-translate-url-to-local-path","errorCode":null,"errorMessage":"Failed to translate <url> to local path","messagePattern":"Failed to translate <url> to local path","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"independent-projects/tools/devtools-common/src/main/java/io/quarkus/platform/descriptor/loader/json/ResourceLoaders.java","lineNumber":84,"sourceCode":"                }\n                return function.apply(localPath);\n            } catch (IOException e) {\n                throw new UncheckedIOException(\"Failed to read \" + jar, e);\n            }\n        }\n\n        if (FILE.equals(url.getProtocol())) {\n            return function.apply(toLocalPath(url));\n        }\n\n        throw new IllegalArgumentException(\"Unexpected protocol \" + url.getProtocol() + \" for URL \" + url);\n    }\n\n    private static Path toLocalPath(final URL url) {\n        try {\n            return Paths.get(url.toURI());\n        } catch (URISyntaxException e) {\n            throw new IllegalArgumentException(\"Failed to translate \" + url + \" to local path\", e);\n        }\n    }\n}\n","sourceCodeStart":66,"sourceCodeEnd":88,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/independent-projects/tools/devtools-common/src/main/java/io/quarkus/platform/descriptor/loader/json/ResourceLoaders.java#L66-L88","documentation":"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').","triggerScenarios":"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.","commonSituations":"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.","solutions":["Construct the URL via File.toURI() or Path.toUri() instead of string concatenation so special characters are encoded","Rename/relocate the offending directory to a path without spaces or special characters","Pre-encode the path portion with URLEncoder/URI multi-arg constructor"],"exampleFix":"// before\nURL url = new URL(\"file:\" + somePath); // breaks on spaces\n// after\nURL url = new File(somePath).toURI().toURL();","handlingStrategy":"validation","validationCode":"static boolean uriSafe(URL url) {\n    try { url.toURI(); return true; } catch (URISyntaxException e) { return false; }\n}","typeGuard":"static boolean isEncodableFileUrl(URL url) {\n    return \"file\".equals(url.getProtocol()) && !url.getPath().matches(\".*[ #\\\\\\\\].*\") || uriSafe(url);\n}","tryCatchPattern":"try {\n    return ResourceLoaders.processAsPath(url, fn);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().startsWith(\"Failed to translate\")) {\n        URL fixed = Paths.get(url.getPath()).toUri().toURL(); // re-encode\n        return ResourceLoaders.processAsPath(fixed, fn);\n    }\n    throw e;\n}","preventionTips":["Create URLs only via File.toURI() / Path.toUri() so spaces and special chars get encoded","Avoid project directories containing spaces or non-ASCII characters in CI images","Never build 'file:' URLs by string concatenation"],"tags":["url","uri","path","encoding"],"backgroundTag":"illegal-uri-characters","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}