kestra-io/kestra · error · IllegalArgumentException

Invalid outputFile (only relative path is supported) for pat

Error message

Invalid outputFile (only relative path is supported) for path '{}'

What it means

Thrown by PluginUtilsService.validFilename() when an output file path starts with './', '..', or '/'. Only strictly relative paths (no leading traversal or absolute-root markers) are permitted, because output files are resolved relative to the task's working directory and an absolute or parent-relative path would escape the sandbox. This is an IllegalArgumentException surfaced during output-file rendering.

Source

Thrown at core/src/main/java/io/kestra/core/models/tasks/runners/PluginUtilsService.java:79

                        String prefix = StringUtils.leftPad(s + "_", 3, "_");
                        tempFile = File.createTempFile(prefix, null, tempDirectory.toFile());
                    }

                    result.put(s, additionalVars.get("workingDir") + "/" + tempFile.getName());
                }));

            if (!isDir) {
                additionalVars.put("temp", result);
            }
            additionalVars.put(isDir ? "outputDirs" : "outputFiles", result);
        }

        return result;
    }

    private static void validFilename(String s) {
        if (s.startsWith("./") || s.startsWith("..") || s.startsWith("/")) {
            throw new IllegalArgumentException(
                "Invalid outputFile (only relative path is supported) " +
                    "for path '" + s + "'"
            );
        }
    }

    public static Map<String, String> transformInputFiles(RunContext runContext, @NotNull Object inputFiles) throws IllegalVariableEvaluationException, JsonProcessingException {
        return PluginUtilsService.transformInputFiles(runContext, Collections.emptyMap(), inputFiles);
    }

    @SuppressWarnings("unchecked")
    public static Map<String, String> transformInputFiles(RunContext runContext, Map<String, Object> additionalVars, @NotNull Object inputFiles)
        throws IllegalVariableEvaluationException, JsonProcessingException {
        if (inputFiles instanceof Map) {
            Map<String, String> castedInputFiles = (Map<String, String>) inputFiles;
            Map<String, String> nullFilteredInputFiles = new HashMap<>();
            castedInputFiles.forEach((key, val) ->
            {

View on GitHub (pinned to 823fada927)

Solutions

Use a bare relative path with no leading './', '..', or '/' (e.g., 'out/data.csv').
If a subdirectory is needed, write 'subdir/file.txt' without a leading slash.
Audit Pebble templates that generate filenames to ensure no leading slash is produced.

Example fix

# before
outputFiles:
  /out/data.csv

# after
outputFiles:
  out/data.csv

Defensive patterns

Strategy: validation

Validate before calling

static void ensureRelative(String s) {
    if (s.startsWith("./") || s.startsWith("..") || s.startsWith("/")) {
        throw new IllegalArgumentException("Only relative paths are allowed: " + s);
    }
}

Type guard

function isSafeRelativePath(p: string): boolean {
  return !p.startsWith('./') && !p.startsWith('..') && !p.startsWith('/');
}

Try / catch

try {
    PluginUtilsService.transformOutputFiles(...);
} catch (IllegalArgumentException e) {
    log.warn("Reject output path: {}", e.getMessage());
}

Prevention

Normalize user-supplied paths to relative form before assignment.
Strip leading './' and '/' from templated filenames.

When it happens

Trigger: A task declares outputFiles with an entry like '/out/data.csv', './out.txt', or '../escape.csv'; a Pebble expression renders to a path with a leading slash; the user sets an absolute path expecting it to be honored.

Common situations: User copies a local absolute path into the flow; template renders an unintended leading './'; confusion between outputFiles (relative) and external paths.

Related errors

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