kestra-io/kestra · error · IllegalArgumentException

The uri '{}' is not a valid file URI.

Error message

The uri '{}' is not a valid file URI.

What it means

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`.

Source

Thrown at core/src/main/java/io/kestra/core/runners/LocalPathFactory.java:62

     */
    public LocalPath createLocalPath(RunContext runContext) {
        return new RunContextLocalPath(globalAllowedPaths, runContext);
    }

    /**
     * Create a LocalPath.
     * If a RunContext is available, this is preferable to use {@link #createLocalPath(RunContext)} as it would be possible to
     * check for paths inside the working directory or allowed inside the plugin configuration.
     */
    public LocalPath createLocalPath() {
        return new DefaultLocalPath(globalAllowedPaths);
    }

    abstract static class AbstractLocalPath implements LocalPath {
        @Override
        public InputStream get(URI uri) throws IOException {
            if (!LocalPath.FILE_SCHEME.equals(uri.getScheme())) {
                throw new IllegalArgumentException("The uri '" + uri + "' is not a valid file URI.");
            }

            Path path = checkPath(uri);
            return new FileInputStream(path.toFile());
        }

        @Override
        public boolean exists(URI uri) throws IOException {
            if (!LocalPath.FILE_SCHEME.equals(uri.getScheme())) {
                throw new IllegalArgumentException("The uri '" + uri + "' is not a valid file URI.");
            }

            Path path = checkPath(uri);
            return Files.exists(path);
        }

        @Override
        public BasicFileAttributes getAttributes(URI uri) throws IOException {

View on GitHub (pinned to 823fada927)

Solutions

  1. Use `runContext.storage().getFile(uri)` for `kestra://` and remote storage URIs, not `LocalPath`.
  2. Convert the path to a `file://` URI before calling `LocalPath.get`.
  3. Ensure the URI was built with `URI.create("file:///abs/path")`.

Example fix

// before
InputStream is = localPath.get(URI.create("kestra:///.../data.csv"));

// after — use storage interface for kestra URIs
InputStream is = runContext.storage().getFile(URI.create("kestra:///.../data.csv"));
Defensive patterns

Strategy: type-guard

Validate before calling

URI uri = ...;
if (!LocalPath.FILE_SCHEME.equals(uri.getScheme())) {
    // use the storage interface for non-file schemes
    return runContext.storage().getFile(uri);
}
return localPath.get(uri);

Type guard

static boolean isFileUri(URI uri) {
    return uri != null && LocalPath.FILE_SCHEME.equals(uri.getScheme());
}

Try / catch

try {
    return localPath.get(uri);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("not a valid file URI")) {
        return runContext.storage().getFile(uri); // fallback for kestra://, s3://, etc.
    }
    throw e;
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of kestra-io/kestra@823fada927 (2026-08-14). Data as JSON: /api/errors/add62cfb18458702. Report an issue: GitHub.