What causes "Failed to create output directory: {}" in kestra-io/kestra?

Choose an output path whose parent directory exists and is writable.

kestra-io/kestra · error · IOException

Failed to create output directory: {}

Error message

Failed to create output directory: {}

What it means

Thrown by 'kestra config schema' when the output directory for the generated schema cannot be created. If output.getParentFile() is non-null, mkdirs() returns false, AND isDirectory() is false, the command throws IOException 'Failed to create output directory: <parent>'. This is a filesystem/permission failure, not a schema-generation failure.

Source

Thrown at cli/src/main/java/io/kestra/cli/schema/ConfigurationSchemaCommand.java:45

        PluginRegistry registry = pluginRegistry;
        if (registry == null && pluginsPath != null) {
            registry = DefaultPluginRegistry.getOrCreate();
            registry.registerIfAbsent(pluginsPath);
        }

        if (registry == null) {
            log.warn("No plugins loaded (no --plugins path provided). Storage plugin schemas will be skipped.");
        }

        var generator = new ConfigurationSchemaGenerator();
        var schema = generator.generate(registry);

        if (
            output.getParentFile() != null && !output.getParentFile().mkdirs()
                && !output.getParentFile().isDirectory()
        ) {
            throw new IOException("Failed to create output directory: " + output.getParentFile());
        }
        ConfigurationSchemaGenerator.write(schema, output);

        stdOut("Configuration schema written to {0}", output.getAbsolutePath());
        return 0;
    }

    @Override
    protected boolean isPluginManagerEnabled() {
        return false;
    }
}

View on GitHub (pinned to 823fada927)

Solutions

Choose an output path whose parent directory exists and is writable.
Pre-create the parent directory manually and pass the file inside it.
Run the Kestra CLI with a user that has write access to the target path.
Avoid pointing --output at a path whose parent collides with an existing file.

Example fix

# before (parent not writable)
kestra config schema --output /readonly/dir/schema.json
# after
mkdir -p /opt/kestra/out && kestra config schema --output /opt/kestra/out/schema.json

Defensive patterns

Strategy: validation

Validate before calling

File parent = output.getParentFile();
if (parent != null && !parent.exists() && !parent.mkdirs()) {
  throw new IOException('Cannot create output directory: ' + parent);
}

Try / catch

try {
  ConfigurationSchemaGenerator.write(schema, output);
} catch (IOException e) {
  throw new CommandLine.ExecutionException(spec.commandLine(), 'Failed to write schema: ' + e.getMessage(), e);
}

Prevention

Pre-create the output directory before running the command.
Run the CLI as a user with write access to the target path.
Avoid parent paths colliding with existing files.

When it happens

Trigger: ConfigurationSchemaCommand resolves output file; output.getParentFile() != null, mkdirs() returns false (or true but a non-dir file exists with that name), isDirectory() returns false; IOException is thrown naming the parent path.

Common situations: Parent path is read-only, a regular file occupies the parent name, the disk is full, the Kestra process lacks write permission on the target location, or the path is invalid for the OS.

Related errors

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