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

Thrown by the 'fileURI' function when the resolved URI scheme is not kestra://, file:// (local), or the namespace file scheme. For kestra:// and file:// it returns the URI as-is; for namespace files it resolves and returns a concrete URI (optionally pinned to a revision). An unsupported scheme hits the default branch and throws IllegalArgumentException.

Source

Thrown at core/src/main/java/io/kestra/core/runners/pebble/functions/FileURIFunction.java:50

        ).toList();
    }

    @Override
    public Map<String, String> getArgumentDefaults() {
        HashMap<String, String> defaults = new HashMap<>();
        defaults.put(PATH, "'a/namespace/file'");
        defaults.put(NAMESPACE, null);
        defaults.put(REVISION, null);
        return defaults;
    }

    @Override
    protected Object fileFunction(EvaluationContext context, URI path, String namespace, String tenantId, Map<String, Object> args) throws IOException {
        return switch (path.getScheme()) {
            case StorageContext.KESTRA_SCHEME -> path.toString();
            case LocalPath.FILE_SCHEME -> path.toString();
            case Namespace.NAMESPACE_FILE_SCHEME -> getNamespaceFileURI(path, namespace, tenantId, args);
            default -> throw new IllegalArgumentException(SCHEME_NOT_SUPPORTED_ERROR.formatted(path));
        };
    }

    private String getNamespaceFileURI(URI path, String namespace, String tenantId, Map<String, Object> args) throws IOException {
        String pathStr = path.getPath();
        if (pathStr.contains("../")) {
            throw new IllegalArgumentException("Path must not contain '../'");
        }
        Namespace namespaceStorage = namespaceFactory.get().of(tenantId, namespace, storageInterface.get());
        Path filePath = NamespaceFile.normalize(Path.of(pathStr));

        if (args.containsKey(REVISION)) {
            Integer revision;
            try {
                revision = Integer.parseInt(args.get(REVISION).toString());
            } catch (NumberFormatException e) {
                throw new IllegalArgumentException("The 'fileURI' function expects the 'revision' argument to be a valid integer.");
            }

View on GitHub (pinned to 823fada927)

Solutions

  1. Pass an internal storage URI (kestra://), a local file:// URI, or a namespace file reference.
  2. For external resources, fetch them into internal storage first and pass the resulting kestra:// URI.
  3. For namespace files, supply the namespace file scheme so the revision/normalization logic applies.

Example fix

# before
uri: "{{ fileURI('https://example.com/x.csv') }}"
# after
uri: "{{ fileURI(outputs.fetch.uri) }}"
Defensive patterns

Strategy: validation

Validate before calling

# Validate the scheme before calling fileURI().
# {{ (uri starts with 'kestra://' or uri starts with 'file://' or uri starts with 'namespace://') ? fileURI(uri) : null }}

Prevention

When it happens

Trigger: Calling fileURI() with an external URL scheme (http, https, s3, gs, ftp) or any non-handled scheme; passing a string that does not parse into one of the supported internal schemes.

Common situations: Using fileURI() to normalize an external download URL; confusing it with a fetch function; passing a plugin-specific URI format.

Related errors

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