kestra-io/kestra · error · SecurityException

The file:// protocol has been disabled inside the Kestra con

Error message

The file:// protocol has been disabled inside the Kestra configuration.

What it means

checkEnabledLocalFileAndReturnNamespace() throws a SecurityException ('The file:// protocol has been disabled inside the Kestra configuration.') when kestra.local-files.enableFileFunctions is false and a file:// path is used. Note this is a SecurityException, NOT IOException/IllegalArgumentException, so it is NOT caught by the surrounding catch block and propagates unwrapped.

Source

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

        if (context.getVariable(TRIGGER) != null) {
            // if there is a trigger of type execution, we also allow accessing a file from the parent execution
            Map<String, String> trigger = (Map<String, String>) context.getVariable(TRIGGER);

            return isFileUriValid(trigger.get(NAMESPACE), trigger.get("flowId"), trigger.get("executionId"), path);
        }
        return false;
    }

    private String checkIfFileFromAllowedNamespaceAndReturnIt(URI path, String tenantId, String fromNamespace) {

        String namespace = extractNamespace(path);
        namespaceService.get().checkAllowedNamespace(tenantId, namespace, tenantId, fromNamespace);
        return namespace;
    }

    private String checkEnabledLocalFileAndReturnNamespace(Map<String, Object> args, Map<String, String> flow) {
        if (!localFilesConfiguration.enableFileFunctions()) {
            throw new SecurityException("The file:// protocol has been disabled inside the Kestra configuration.");
        }

        return (String) Optional.ofNullable(args.get(NAMESPACE)).orElse(flow.get(NAMESPACE));
    }

    private String checkedAllowedNamespaceAndReturnNamespace(Map<String, Object> args, URI nsFileUri, String tenantId, Map<String, String> flow) {
        if (args.get(NAMESPACE) != null && nsFileUri.getAuthority() != null) {
            throw new IllegalArgumentException("You cannot set a namespace both as the function argument and inside the URI");
        }

        // we will transform nsfile URI into a kestra URI so it is handled seamlessly by all functions
        String customNs = Optional.ofNullable((String) args.get(NAMESPACE)).orElse(nsFileUri.getAuthority());
        if (customNs != null) {
            namespaceService.get().checkAllowedNamespace(tenantId, customNs, tenantId, flow.get(NAMESPACE));
        }
        return Optional.ofNullable(customNs).orElse(flow.get(NAMESPACE));
    }

View on GitHub (pinned to 823fada927)

Solutions

1. Avoid file:// paths; use kestra:/// internal storage or namespace:// files instead.
2. If legitimate, ask the admin to set kestra.local-files.enableFileFunctions=true (and restrict allowedPaths) in the Kestra configuration.
3. Move the needed file into internal storage via a task, then reference the kestra:/// URI.

Example fix

// before
{{ read('file:///tmp/data.txt') }}
// after
{{ read('namespace:///company.team/data.txt') }}

// Pebble: avoid file:// unless you know it is enabled
{% if (enabled is defined) and enabled %}{{ read('file:///tmp/data') }}{% else %}{{ read('namespace:///company.team/data.txt') }}{% endif %}

// Java: SecurityException is NOT caught by the IO/IAE catch — handle it explicitly
try {
    fileFunction.execute(args, self, context, line);
} catch (SecurityException e) {
    // file:// disabled in kestra.local-files; use internal storage
}

When it happens

Trigger: Using {{ read('file:///etc/hosts') }} (or file:// local paths) in an environment where the admin set kestra.local-files.enableFileFunctions=false (or the property resolved to false).

Common situations: Hardened/production Kestra deployments that disable local file access for security; misconfigured kestra.local-files; assuming local file access is always enabled (default true but often turned off).

Related errors

• The URI {} is not in the configured allowed list (kestra.tas
• The URI {} is in the configured denied list (kestra.tasks.ht
• The path {} is not authorized. Only files inside the working
• The path {} is not authorized. Path must be allowed either g
• Both username and password must be provided if either is pre

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