kestra-io/kestra · error · IllegalArgumentException

Cannot create a working directory file with a null or empty

Error message

Cannot create a working directory file with a null or empty name

What it means

Thrown by `LocalWorkingDir.createFile(String, ...)` when the filename is null or blank. `createFile` writes a new file inside the working directory; a missing name is a programming error. Thrown as `IllegalArgumentException` before any filesystem operation.

Source

Thrown at core/src/main/java/io/kestra/core/runners/LocalWorkingDir.java:164

    public Path createFile(String filename) throws IOException {
        return createFile(filename, (InputStream) null);
    }

    /**
     * {@inheritDoc}
     **/
    @Override
    public Path createFile(String filename, byte[] content) throws IOException {
        return createFile(filename, content == null ? null : new ByteArrayInputStream(content));
    }

    /**
     * {@inheritDoc}
     **/
    @Override
    public Path createFile(String filename, InputStream content) throws IOException {
        if (filename == null || filename.isBlank()) {
            throw new IllegalArgumentException("Cannot create a working directory file with a null or empty name");
        }
        Path newFilePath = this.resolve(Path.of(filename));
        Files.createDirectories(newFilePath.getParent());

        Files.createFile(newFilePath);

        if (content != null) {
            try (content) {
                Files.copy(content, newFilePath, REPLACE_EXISTING);
            }
        }

        return newFilePath;
    }

    /**
     * {@inheritDoc}
     **/

View on GitHub (pinned to 823fada927)

Solutions

1. Provide a non-blank filename; fall back to a generated name when the source is empty.
2. Use `workingDir.createTempFile()` when you do not need a specific name.
3. Validate the filename is non-blank before calling `createFile`.

Example fix

// before
String name = maybeName; // null
Path p = workingDir.createFile(name, bytes);

// after
String name = (maybeName == null || maybeName.isBlank())
    ? "file-" + IdUtils.create() + ".tmp"
    : maybeName;
Path p = workingDir.createFile(name, bytes);

if (filename == null || filename.isBlank()) {
    filename = "file-" + IdUtils.create() + ".tmp";
}
return workingDir.createFile(filename, content);

static boolean isValidFilename(String name) {
    return name != null && !name.isBlank();
}

When it happens

Trigger: Calling `workingDir.createFile(null, bytes)`, `workingDir.createFile("", stream)`, or `workingDir.createFile(" ")`. The filename usually comes from a Pebble-rendered variable, an output name, or a downloaded file's name — if that source is empty/null, this fires.

Common situations: A download task where the remote filename header is missing; a Pebble expression that renders to empty (`{{ missing.var }}` with no default); passing `output.fileName` when the output has no filename attribute.

Related errors

• Cannot create a working directory file with a null path
• Cannot create a working directory file with an empty inputSt
• The path to resolve must be a relative path inside the curre
• File {} already exist
• Invalid flow path

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