{"record":{"id":"add62cfb18458702","repo":"kestra-io/kestra","slug":"the-uri-is-not-a-valid-file-uri","errorCode":null,"errorMessage":"The uri '{}' is not a valid file URI.","messagePattern":"The uri '(.+?)' is not a valid file URI\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/io/kestra/core/runners/LocalPathFactory.java","lineNumber":62,"sourceCode":"     */\n    public LocalPath createLocalPath(RunContext runContext) {\n        return new RunContextLocalPath(globalAllowedPaths, runContext);\n    }\n\n    /**\n     * Create a LocalPath.\n     * If a RunContext is available, this is preferable to use {@link #createLocalPath(RunContext)} as it would be possible to\n     * check for paths inside the working directory or allowed inside the plugin configuration.\n     */\n    public LocalPath createLocalPath() {\n        return new DefaultLocalPath(globalAllowedPaths);\n    }\n\n    abstract static class AbstractLocalPath implements LocalPath {\n        @Override\n        public InputStream get(URI uri) throws IOException {\n            if (!LocalPath.FILE_SCHEME.equals(uri.getScheme())) {\n                throw new IllegalArgumentException(\"The uri '\" + uri + \"' is not a valid file URI.\");\n            }\n\n            Path path = checkPath(uri);\n            return new FileInputStream(path.toFile());\n        }\n\n        @Override\n        public boolean exists(URI uri) throws IOException {\n            if (!LocalPath.FILE_SCHEME.equals(uri.getScheme())) {\n                throw new IllegalArgumentException(\"The uri '\" + uri + \"' is not a valid file URI.\");\n            }\n\n            Path path = checkPath(uri);\n            return Files.exists(path);\n        }\n\n        @Override\n        public BasicFileAttributes getAttributes(URI uri) throws IOException {","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/kestra-io/kestra/blob/823fada9274c4f9c251ea0a516460a4f7d958032/core/src/main/java/io/kestra/core/runners/LocalPathFactory.java#L44-L80","documentation":"Thrown by `LocalPathFactory.AbstractLocalPath.get(URI)` when the supplied URI's scheme is not `file` (the value of `LocalPath.FILE_SCHEME`). `LocalPath` is the file-system backend used by the `LocalFiles` task and `file://` URI resolution inside a task's working directory; it only handles the `file` scheme. The placeholder is the offending URI. Thrown as `IllegalArgumentException`.","triggerScenarios":"Calling `localPath.get(uri)` (reading a file via `InMemoryFiles`/`LocalFiles` or an internal `URI`-based fetch) with a URI whose scheme is `http`, `https`, `gs`, `s3`, `kestra://`, or null. Only `file://...` URIs are accepted by this backend.","commonSituations":"Passing an internal-storage `kestra://` URI to a local-file reader instead of using `runContext.storage().getFile()`; mixing a remote URL where a local path is required; a URI created without an explicit scheme.","solutions":["Use `runContext.storage().getFile(uri)` for `kestra://` and remote storage URIs, not `LocalPath`.","Convert the path to a `file://` URI before calling `LocalPath.get`.","Ensure the URI was built with `URI.create(\"file:///abs/path\")`."],"exampleFix":"// before\nInputStream is = localPath.get(URI.create(\"kestra:///.../data.csv\"));\n\n// after — use storage interface for kestra URIs\nInputStream is = runContext.storage().getFile(URI.create(\"kestra:///.../data.csv\"));","handlingStrategy":"type-guard","validationCode":"URI uri = ...;\nif (!LocalPath.FILE_SCHEME.equals(uri.getScheme())) {\n    // use the storage interface for non-file schemes\n    return runContext.storage().getFile(uri);\n}\nreturn localPath.get(uri);","typeGuard":"static boolean isFileUri(URI uri) {\n    return uri != null && LocalPath.FILE_SCHEME.equals(uri.getScheme());\n}","tryCatchPattern":"try {\n    return localPath.get(uri);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"not a valid file URI\")) {\n        return runContext.storage().getFile(uri); // fallback for kestra://, s3://, etc.\n    }\n    throw e;\n}","preventionTips":["Route `kestra://` and remote URIs through `runContext.storage()`, not `LocalPath`.","Build local URIs with `file://` and an absolute path.","Centralize URI dispatch in a helper that checks the scheme."],"tags":["local-files","uri","scheme","io"],"backgroundTag":null,"analyzedSha":"823fada9274c4f9c251ea0a516460a4f7d958032","analyzedAt":"2026-08-14T06:15:17.947Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}