kestra-io/kestra · error · PebbleException

IOException|IllegalArgumentException: e.getMessage()

Error message

IOException|IllegalArgumentException: e.getMessage()

What it means

This is the catch block in AbstractFileFunction.execute() that converts IOException or IllegalArgumentException into a PebbleException using e.getMessage(). It is the single rethrow point for several distinct upstream failures: path-traversal checks, URI parsing errors, the 'scheme not supported' IllegalArgumentException, the 'namespace set in two places' error, and the 'not an execution file' error. The message you see is the wrapped exception's own message.

Source

Thrown at core/src/main/java/io/kestra/core/runners/pebble/functions/AbstractFileFunction.java:102

                    fileUri = URI.create(str);
                    namespace = checkEnabledLocalFileAndReturnNamespace(args, flow);
                } else if (str.startsWith(Namespace.NAMESPACE_FILE_SCHEME)) {
                    fileUri = URI.create(str);
                    namespace = checkedAllowedNamespaceAndReturnNamespace(args, fileUri, tenantId, flow);
                } else if (URI_PATTERN.matcher(str).matches()) {
                    // it is an unsupported URI
                    throw new IllegalArgumentException(SCHEME_NOT_SUPPORTED_ERROR.formatted(str));
                } else {
                    fileUri = URI.create(Namespace.NAMESPACE_FILE_SCHEME + ":///" + str);
                    namespace = (String) Optional.ofNullable(args.get(NAMESPACE)).orElse(flow.get(NAMESPACE));
                    namespaceService.get().checkAllowedNamespace(tenantId, namespace, tenantId, flow.get(NAMESPACE));
                }
            } else {
                throw new PebbleException(null, "Unable to read the file " + path, lineNumber, self.getName());
            }
            return fileFunction(context, fileUri, namespace, tenantId, args);
        } catch (IOException | IllegalArgumentException e) { // IllegalArgumentException may be thrown for path traversal, catch it to have proper error handling
            throw new PebbleException(e, e.getMessage(), lineNumber, self.getName());
        }
    }

    @Override
    public List<String> getArgumentNames() {
        return List.of(PATH, NAMESPACE);
    }

    @Override
    public Map<String, String> getArgumentDefaults() {
        return Map.of(
            PATH, "outputs.download.uri",
            NAMESPACE, "flow.namespace"
        );
    }

    protected abstract String getErrorMessage();

View on GitHub (pinned to 823fada927)

Solutions

Read the wrapped message to identify the real cause (scheme, traversal, not-an-execution-file, namespace conflict, or IO).
Use URIs produced by tasks (outputs.*.uri) rather than hand-built strings.
Verify namespace access is permitted for the executing tenant/namespace.

Defensive patterns

Strategy: try-catch

Try / catch

// Read the wrapped PebbleException message to branch on root cause
try {
    Object result = fileFunction.execute(args, self, context, lineNumber);
} catch (PebbleException e) {
    String msg = e.getMessage();
    if (msg.contains("scheme not supported")) { /* use HTTP task */ }
    else if (msg.contains("not an execution file")) { /* fix URI shape */ }
    else if (msg.contains("namespace both")) { /* remove duplicate */ }
    else { /* IO/path-traversal: check storage + tenant access */ }
}

Prevention

Use URIs from task outputs to avoid malformed-path errors.
Verify namespace/tenant access is permitted.
Inspect the wrapped message to locate the real upstream failure.

When it happens

Trigger: Any of: malformed kestra:/// URI failing URI.create; IllegalArgumentException from extractNamespace (not an execution file); IllegalArgumentException from checkedAllowedNamespaceAndReturnNamespace (namespace set twice); path-traversal rejection; IOException from the underlying fileFunction reading internal storage.

Common situations: Hand-typed internal storage URIs that are malformed; cross-namespace access blocked by tenancy; storage backend unreachable (IOException); namespace mismatch between argument and URI authority.

Related errors

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