{"record":{"id":"aec99a3739d7ae0a","repo":"java-native-access/jna","slug":"file-url-url-could-not-be-properly-decoded","errorCode":null,"errorMessage":"File URL url could not be properly decoded","messagePattern":"File URL url could not be properly decoded","errorType":"exception","errorClass":"java.io.IOException","httpStatus":null,"severity":"error","filePath":"src/com/sun/jna/Native.java","lineNumber":1224,"sourceCode":"            String path = System.getProperty(\"java.class.path\");\n            if (loader instanceof URLClassLoader) {\n                path = Arrays.asList(((URLClassLoader)loader).getURLs()).toString();\n            }\n            throw new IOException(\"Native library (\" + resourcePath + \") not found in resource path (\" + path + \")\");\n        }\n        LOG.log(DEBUG, \"Found library resource at {0}\", url);\n\n        File lib = null;\n        if (url.getProtocol().toLowerCase().equals(\"file\")) {\n            try {\n                lib = new File(new URI(url.toString()));\n            }\n            catch(URISyntaxException e) {\n                lib = new File(url.getPath());\n            }\n            LOG.log(DEBUG, \"Looking in {0}\", lib.getAbsolutePath());\n            if (!lib.exists()) {\n                throw new IOException(\"File URL \" + url + \" could not be properly decoded\");\n            }\n        }\n        else if (!Boolean.getBoolean(\"jna.nounpack\")) {\n            InputStream is = url.openStream();\n            if (is == null) {\n                throw new IOException(\"Can't obtain InputStream for \" + resourcePath);\n            }\n\n            FileOutputStream fos = null;\n            try {\n                // Suffix is required on windows, or library fails to load\n                // Let Java pick the suffix, except on windows, to avoid\n                // problems with Web Start.\n                File dir = getTempDir();\n                lib = File.createTempFile(JNA_TMPLIB_PREFIX, Platform.isWindows()?\".dll\":null, dir);\n                if (!Boolean.getBoolean(\"jnidispatch.preserve\")) {\n                    lib.deleteOnExit();\n                }","sourceCodeStart":1206,"sourceCodeEnd":1242,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/src/com/sun/jna/Native.java#L1206-L1242","documentation":"When the resolved resource URL uses the file protocol, JNA converts it to a File and checks existence; if the file the URL points to does not exist (e.g. the URL was built from a path with characters that failed URI decoding, or the target was deleted), it throws IOException 'File URL <url> could not be properly decoded'. It guards against silently using a wrong file path obtained from a malformed file: URL.","triggerScenarios":"extractFromResourcePath resolving a file: URL whose path contains spaces, unicode, or '+' characters that URL-decoding mangles, producing a nonexistent File; or the classpath entry pointing at a file removed after JVM start.","commonSituations":"Classpath directories with spaces or non-ASCII names; loading JNA from a UNC/mounted path; jars-in-paths whose name changed while the JVM ran; frameworks constructing file: URLs manually without proper encoding.","solutions":["Move the JNA JAR/classpath entry to a path without spaces or special characters, or properly URL-encode the path","Verify the file in the message exists at the decoded path; fix the classpath entry if it points at a stale location","Rebuild/redeploy the artifact if the referenced file was removed (stale deployment)","As a workaround, install the native library on disk and load via jna.boot.library.path rather than resource extraction"],"exampleFix":"// before\nURL url = new File(\"/opt/My Lib/jna.jar\").toURL(); // legacy, unencoded\n// after\nURL url = new File(\"/opt/My Lib/jna.jar\").toURI().toURL(); // properly encoded file URI","handlingStrategy":"validation","validationCode":"// check that the file: URL path survives URI round-trip and exists\nURL u = loader.getResource(res);\nif (u != null && \"file\".equals(u.getProtocol())) {\n    File f = new File(u.getPath());\n    if (!f.exists()) throw new IllegalStateException(\"Classpath file URL broken (spaces/special chars?): \" + u);\n}","typeGuard":null,"tryCatchPattern":"try { Native.extractFromResourcePath(res, loader); } catch (IOException e) { if (String.valueOf(e.getMessage()).startsWith(\"File URL \")) { throw new IllegalStateException(\"Path with spaces/unicode or stale classpath entry: \" + e.getMessage(), e); } throw e; }","preventionTips":["Avoid spaces and non-ASCII characters in classpath directories","Use toURI().toURL() (not deprecated toURL()) when constructing file URLs","Redeploy cleanly if files referenced by the running JVM were deleted"],"tags":["java","io","url-decode","file-not-found"],"backgroundTag":"invalid-url-format","analyzedSha":"d036ad9781adad4b66693e8fa7098e4ac665e0a3","analyzedAt":"2026-09-12T06:50:59.239Z","contentChangedAt":"2026-09-12T06:50:59.239Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}