apache/seatunnel · error · IllegalArgumentException

Single file mode is not supported when file_name_expression

Error message

Single file mode is not supported when file_name_expression not contains <DEFAULT_FILE_NAME_EXPRESSION> but has parallel subtasks.

What it means

BaseFileSinkWriter validates at startup that single-file mode (writing all subtasks into one file) cannot be combined with parallel subtasks when file_name_expression is set but does not contain the placeholder that makes each subtask's filename unique. Without the placeholder, parallel subtasks would collide writing the same file. This is a fail-fast IllegalArgumentException thrown during sink configuration pre-check.

Source

Thrown at seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/sink/BaseFileSinkWriter.java:128

                        writeStrategy.getFileSinkConfig().getFileNameExpression())) {
            throw new IllegalArgumentException(
                    "Binary custom filename requires a unique filename expression when parallel "
                            + "subtasks are used. Please include "
                            + DEFAULT_FILE_NAME_EXPRESSION
                            + " or ${"
                            + Constants.UUID
                            + "} in "
                            + FILE_NAME_EXPRESSION.key()
                            + ".");
        }
        if (writeStrategy.getFileSinkConfig().isSingleFileMode()
                && context.getNumberOfParallelSubtasks() > 1) {
            if (StringUtils.isNotEmpty(writeStrategy.getFileSinkConfig().getFileNameExpression())
                    && !writeStrategy
                            .getFileSinkConfig()
                            .getFileNameExpression()
                            .contains(DEFAULT_FILE_NAME_EXPRESSION)) {
                throw new IllegalArgumentException(
                        "Single file mode is not supported when "
                                + FILE_NAME_EXPRESSION.key()
                                + " not contains "
                                + DEFAULT_FILE_NAME_EXPRESSION
                                + " but has parallel subtasks.");
            }
        }
    }

    private boolean hasParallelUniqueFilenameExpression(String fileNameExpression) {
        return StringUtils.isBlank(fileNameExpression)
                || fileNameExpression.contains(DEFAULT_FILE_NAME_EXPRESSION)
                || fileNameExpression.contains("${" + Constants.UUID + "}");
    }

    private List<String> findTransactionList(
            String jobId, String uuidPrefix, HadoopFileSystemProxy hadoopFileSystemProxy)
            throws IOException {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Include the placeholder in file_name_expression, e.g. 'data_${date}_<DEFAULT_FILE_NAME_EXPRESSION>' or set sink.parallelism=1.
2. Set file_name_expression to null/omit it so the default per-subtask naming is used.
3. If a truly single output file is required, set single_file_mode=false and parallelism=1, or write to a single partition and merge downstream.

Example fix

// before
sink {
  FakeSource {
    parallelism = 4
    file_name_expression = "out_${now}"
    single_file_mode = true
  }
}
// after
sink {
  FakeSource {
    parallelism = 4
    file_name_expression = "out_${now}_<DEFAULT_FILE_NAME_EXPRESSION>"
    single_file_mode = true
  }
}

if (config.singleFileMode && parallelism > 1 && config.fileNameExpression != null && !config.fileNameExpression.contains("<DEFAULT_FILE_NAME_EXPRESSION>")) {
  throw new IllegalArgumentException("file_name_expression must contain <DEFAULT_FILE_NAME_EXPRESSION> in parallel single-file mode");
}

When it happens

Trigger: Creating a file sink with parallelism > 1, single_file_mode=true, a non-empty file_name_expression that lacks the <DEFAULT_FILE_NAME_EXPRESSION> (or format-specific) placeholder token.

Common situations: Users set a custom file_name_expression like 'data_${date}' for parallel batch jobs; multi-thread/multi-node writes with custom names; copy-pasting single-machine configs into a cluster job.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• Subtask ID ${subTaskId} is out of server id range ${this}, p
• ILLEGAL_ARGUMENT
• CanalJson file does not support this compress type: {}
• prepare method is not supported
• Option not be null.

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/fe4785ee70d9cb71. Report an issue: GitHub.