kestra-io/kestra · error · IllegalArgumentException

Scheme not supported: {}. Supported schemes are: {}

Error message

Scheme not supported: {}. Supported schemes are: {}

What it means

Thrown by the URIFetcher(URI) constructor when the URI's scheme is not in SUPPORTED_SCHEMES, which is the fixed list [kestra://, file://, namespace://]. URIFetcher is the typed reader for property URIs resolved at execution time, and it refuses to construct for schemes it cannot fetch (e.g., http, https, s3, gs). The message echoes both the bad scheme and the full supported list for self-correction.

Source

Thrown at core/src/main/java/io/kestra/core/models/property/URIFetcher.java:40

    /**
     * Build a new URI Fetcher from a String URI.
     * WARNING: the URI must be rendered before.
     *
     * A factory method is also provided for fluent style programming, see {@link #of(String).}
     */
    public URIFetcher(String uri) {
        this(URI.create(uri));
    }

    /**
     * Build a new URI Fetcher from a URI.
     *
     * A factory method is also provided for fluent style programming, see {@link #of(URI).}
     */
    public URIFetcher(URI uri) {
        if (SUPPORTED_SCHEMES.stream().noneMatch(s -> s.equals(uri.getScheme()))) {
            throw new IllegalArgumentException("Scheme not supported: " + uri.getScheme() + ". Supported schemes are: " + SUPPORTED_SCHEMES);
        }

        this.uri = uri;
    }

    /**
     * Build a new URI Fetcher from a String URI.
     * WARNING: the URI must be rendered before.
     */
    public static URIFetcher of(String uri) {
        return new URIFetcher(uri);
    }

    /**
     * Build a new URI Fetcher from a URI.
     */
    public static URIFetcher of(URI uri) {
        return new URIFetcher(uri);

View on GitHub (pinned to 823fada927)

Solutions

  1. Use 'kestra://' for internal storage, 'namespace://' for namespace files, or 'file://' for worker-local files.
  2. If you need HTTP content, download it into internal storage first, then reference the kestra:// URI.
  3. Verify the rendered URI scheme before constructing the fetcher.

Example fix

// before
new URIFetcher("https://example.com/data.csv")
// IllegalArgumentException: Scheme not supported: https

// after
URI stored = runContext.storage().putFile(downloadedFile);
new URIFetcher(stored);   // kestra://...
Defensive patterns

Strategy: validation

Validate before calling

List<String> SUPPORTED = List.of("kestra", "file", "namespace");
if (uri.getScheme() == null || !SUPPORTED.contains(uri.getScheme())) {
    throw new IllegalArgumentException("Scheme not supported: " + uri.getScheme());
}

Type guard

function isSupportedScheme(uri: string): boolean {
  return /^(kestra|file|namespace):\/\//.test(uri);
}

Try / catch

try {
    new URIFetcher(uri);
} catch (IllegalArgumentException e) {
    // fetch external content into storage first, then retry with kestra://
    log.warn("Unsupported URI scheme; download into internal storage first.");
}

Prevention

When it happens

Trigger: Passing an http(s):// URI to new URIFetcher(...) or URIFetcher.of(...); passing a cloud-storage scheme (s3://, gs://); passing a relative path with no scheme; a Pebble-rendered URI resolves to an unexpected scheme.

Common situations: A task property is set to an external URL instead of a Kestra internal storage reference; plugin author assumes HTTP is supported; the URI was rendered from a variable that contained a full URL.

Related errors

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