{"record":{"id":"f658c9a3f57a03b7","repo":"kestra-io/kestra","slug":"the-file-protocol-has-been-disabled-inside-the","errorCode":null,"errorMessage":"The file:// protocol has been disabled inside the Kestra configuration.","messagePattern":"The file:// protocol has been disabled inside the Kestra configuration\\.","errorType":"exception","errorClass":"SecurityException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/io/kestra/core/runners/pebble/functions/AbstractFileFunction.java","lineNumber":175,"sourceCode":"        if (context.getVariable(TRIGGER) != null) {\n            // if there is a trigger of type execution, we also allow accessing a file from the parent execution\n            Map<String, String> trigger = (Map<String, String>) context.getVariable(TRIGGER);\n\n            return isFileUriValid(trigger.get(NAMESPACE), trigger.get(\"flowId\"), trigger.get(\"executionId\"), path);\n        }\n        return false;\n    }\n\n    private String checkIfFileFromAllowedNamespaceAndReturnIt(URI path, String tenantId, String fromNamespace) {\n\n        String namespace = extractNamespace(path);\n        namespaceService.get().checkAllowedNamespace(tenantId, namespace, tenantId, fromNamespace);\n        return namespace;\n    }\n\n    private String checkEnabledLocalFileAndReturnNamespace(Map<String, Object> args, Map<String, String> flow) {\n        if (!localFilesConfiguration.enableFileFunctions()) {\n            throw new SecurityException(\"The file:// protocol has been disabled inside the Kestra configuration.\");\n        }\n\n        return (String) Optional.ofNullable(args.get(NAMESPACE)).orElse(flow.get(NAMESPACE));\n    }\n\n    private String checkedAllowedNamespaceAndReturnNamespace(Map<String, Object> args, URI nsFileUri, String tenantId, Map<String, String> flow) {\n        if (args.get(NAMESPACE) != null && nsFileUri.getAuthority() != null) {\n            throw new IllegalArgumentException(\"You cannot set a namespace both as the function argument and inside the URI\");\n        }\n\n        // we will transform nsfile URI into a kestra URI so it is handled seamlessly by all functions\n        String customNs = Optional.ofNullable((String) args.get(NAMESPACE)).orElse(nsFileUri.getAuthority());\n        if (customNs != null) {\n            namespaceService.get().checkAllowedNamespace(tenantId, customNs, tenantId, flow.get(NAMESPACE));\n        }\n        return Optional.ofNullable(customNs).orElse(flow.get(NAMESPACE));\n    }\n","sourceCodeStart":157,"sourceCodeEnd":193,"githubUrl":"https://github.com/kestra-io/kestra/blob/823fada9274c4f9c251ea0a516460a4f7d958032/core/src/main/java/io/kestra/core/runners/pebble/functions/AbstractFileFunction.java#L157-L193","documentation":"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.","triggerScenarios":"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).","commonSituations":"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).","solutions":["Avoid file:// paths; use kestra:/// internal storage or namespace:// files instead.","If legitimate, ask the admin to set kestra.local-files.enableFileFunctions=true (and restrict allowedPaths) in the Kestra configuration.","Move the needed file into internal storage via a task, then reference the kestra:/// URI."],"exampleFix":"// before\n{{ read('file:///tmp/data.txt') }}\n// after\n{{ read('namespace:///company.team/data.txt') }}","handlingStrategy":"validation","validationCode":"// Pebble: avoid file:// unless you know it is enabled\n{% if (enabled is defined) and enabled %}{{ read('file:///tmp/data') }}{% else %}{{ read('namespace:///company.team/data.txt') }}{% endif %}","typeGuard":null,"tryCatchPattern":"// Java: SecurityException is NOT caught by the IO/IAE catch — handle it explicitly\ntry {\n    fileFunction.execute(args, self, context, line);\n} catch (SecurityException e) {\n    // file:// disabled in kestra.local-files; use internal storage\n}","preventionTips":["Prefer kestra:/// or namespace:// URIs over file://.","Confirm kestra.local-files.enableFileFunctions is true before relying on file://.","Treat a disabled local-files config as a security boundary, not a bug."],"tags":["pebble","function","security","configuration","local-files"],"backgroundTag":null,"analyzedSha":"823fada9274c4f9c251ea0a516460a4f7d958032","analyzedAt":"2026-08-14T06:15:17.947Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}