apache/flink · error · IllegalArgumentException

Output file path may not be null.

Error message

Output file path may not be null.

What it means

Thrown by FileOutputFormat.setOutputFilePath(Path) when the argument is null. The output path is a mandatory sink attribute; a null value would later cause NPEs during path resolution, so it is rejected eagerly at the setter.

Source

Thrown at flink-core/src/main/java/org/apache/flink/api/common/io/FileOutputFormat.java:130

    private transient Path actualFilePath;

    /**
     * Flag indicating whether this format actually created a file, which should be removed on
     * cleanup.
     */
    private transient boolean fileCreated;

    // --------------------------------------------------------------------------------------------

    public FileOutputFormat() {}

    public FileOutputFormat(Path outputPath) {
        this.outputFilePath = outputPath;
    }

    public void setOutputFilePath(Path path) {
        if (path == null) {
            throw new IllegalArgumentException("Output file path may not be null.");
        }

        this.outputFilePath = path;
    }

    public Path getOutputFilePath() {
        return this.outputFilePath;
    }

    public void setWriteMode(WriteMode mode) {
        if (mode == null) {
            throw new NullPointerException();
        }

        this.writeMode = mode;
    }

    public WriteMode getWriteMode() {

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Pass a non-null Path constructed from a known base URI and filename.
2. If the path is config-driven, validate the config value is present before constructing the Path.
3. Prefer the FileOutputFormat(Path) constructor which sets the path in one step.

Example fix

// before
FileOutputFormat out = new FileOutputFormat();
out.setOutputFilePath(pathFromConfig); // pathFromConfig is null

// after
Path outPath = new Path(requireNonNull(pathFromConfig, "output path config missing"));
FileOutputFormat out = new FileOutputFormat(outPath);

Path out = Objects.requireNonNull(pathFromConfig, "output path config must be present");
FileOutputFormat format = new FileOutputFormat(out);

// Ensure the path is non-null before calling the setter
static Path requireOutputPath(String uri) {
    if (uri == null || uri.isEmpty()) {
        throw new IllegalArgumentException("output path uri is required");
    }
    return new Path(uri);
}

When it happens

Trigger: Calling setOutputFilePath(null); passing a Path variable that was never assigned; a config-driven path that resolves to null (e.g., missing config key) before being set on the format.

Common situations: Building a FileOutputFormat dynamically where the path comes from a config/parameter that wasn't provided; refactoring that removes the assignment; tests that construct the format without a path then call the setter with a null placeholder.

Related errors

• The file path is null.
• Delimiter must not be null
• Number of input splits has to be at least 1.
• TaskNumber: {}, numTasks: {}
• Output path '{}' could not be initialized. Canceling task...

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/a670f4f1de812273. Report an issue: GitHub.