What causes "Cannot process the URI %s: scheme not supported." in kestra-io/kestra?

Use a 'kestra://' internal-storage URI, an 'nsfile://' namespace-file URI, or a relative namespace path string.

kestra-io/kestra · error · IllegalArgumentException

Cannot process the URI %s: scheme not supported.

Error message

Cannot process the URI %s: scheme not supported.

What it means

The isFileEmpty function only handles three URI schemes: 'kestra://' (internal storage), 'file://' (local files, if enabled), and 'nsfile://' (namespace files). Any other scheme reaches the switch default and throws. The IllegalArgumentException is caught and rethrown by AbstractFileFunction as a PebbleException with the same message.

Source

Thrown at core/src/main/java/io/kestra/core/runners/pebble/functions/IsFileEmptyFunction.java:44

            case StorageContext.KESTRA_SCHEME -> {
                try (InputStream inputStream = storageInterface.get().get(tenantId, namespace, path)) {
                    byte[] buffer = new byte[1];
                    yield inputStream.read(buffer, 0, 1) <= 0;
                }
            }
            case LocalPath.FILE_SCHEME -> {
                try (InputStream inputStream = localPathFactory.get().createLocalPath().get(path)) {
                    byte[] buffer = new byte[1];
                    yield inputStream.read(buffer, 0, 1) <= 0;
                }
            }
            case Namespace.NAMESPACE_FILE_SCHEME -> {
                FileAttributes fileAttributes = namespaceFactory.get()
                    .of(tenantId, namespace, storageInterface.get())
                    .getFileMetadata(NamespaceFile.normalize(Path.of(path.getPath())));
                yield fileAttributes.getSize() <= 0;
            }
            default -> throw new IllegalArgumentException(SCHEME_NOT_SUPPORTED_ERROR.formatted(path));
        };
    }

    @Override
    protected String getErrorMessage() {
        return ERROR_MESSAGE;
    }
}

View on GitHub (pinned to 823fada927)

Solutions

Use a 'kestra://' internal-storage URI, an 'nsfile://' namespace-file URI, or a relative namespace path string.
For remote URLs, download the file into internal storage first, then check emptiness.
If you need 'file://', enable local file functions in the Kestra configuration (kestra.plugins.local-files.enableFileFunctions).

Example fix

// before
{{ isFileEmpty('https://example.com/data.csv') }}
// after — check an internal-storage URI
{{ isFileEmpty('kestra:///com.acme/myflow/executions/.../tasks/.../data.csv') }}

Defensive patterns

Strategy: validation

Validate before calling

{% set s = myPath|slice(0, 7) %}{% if s in ['kestra:', 'nsfile:', 'file://'] %}{{ isFileEmpty(myPath) }}{% else %}unsupported-scheme{% endif %}

Prevention

Use only 'kestra://', 'nsfile://', or (if enabled) 'file://' URIs, or a relative namespace path.
Download remote URLs into internal storage before checking emptiness.
Remember isFileEmpty does not read arbitrary http/s3/gs URLs.

When it happens

Trigger: Passing a path like 's3://bucket/key', 'http://example.com/file', or any URI whose scheme is not kestra, file, or nsfile.

Common situations: Assuming the function reads arbitrary remote URLs or cloud object stores; passing a plain 'https://' URL; or passing a URI object constructed with a foreign scheme.

Related errors

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