What causes "FILE_FIELDS_DELIMITER must be a single character" in apache/seatunnel?

Set file_fields_delimiter to exactly one character, e.g. file_fields_delimiter = ","

apache/seatunnel · error · ClickhouseConnectorException

SEA-TUNNEL-API-01

SEA-TUNNEL-API-01

Error message

FILE_FIELDS_DELIMITER must be a single character

What it means

The ClickHouse file sink validates that the `file_fields_delimiter` config option is exactly one character, because the delimiter is written directly into ClickHouseLocal FORMAT/CSV settings and multi-character delimiters produce malformed files. It throws a CONFIG_VALIDATION_FAILED exception from ClickhouseFileSinkFactory.createSink when the configured value's length is not 1.

Source

Thrown at seatunnel-connectors-v2/connector-clickhouse/src/main/java/org/apache/seatunnel/connectors/seatunnel/clickhouse/sink/file/ClickhouseFileSinkFactory.java:151

                                                configObject.toConfig().getString(NODE_ADDRESS),
                                        configObject ->
                                                configObject.toConfig().hasPath(USERNAME.key())
                                                        ? configObject
                                                                .toConfig()
                                                                .getString(USERNAME.key())
                                                        : "root"));

        Map<String, String> nodePassword =
                readonlyConfig.get(NODE_PASS).stream()
                        .collect(
                                Collectors.toMap(
                                        NodePassConfig::getNodeAddress,
                                        NodePassConfig::getPassword));

        proxy.close();

        if (readonlyConfig.get(FILE_FIELDS_DELIMITER).length() != 1) {
            throw new ClickhouseConnectorException(
                    SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED,
                    FILE_FIELDS_DELIMITER.key() + " must be a single character");
        }
        FileReaderOption readerOption =
                new FileReaderOption(
                        shardMetadata,
                        tableSchema,
                        fields,
                        readonlyConfig.get(CLICKHOUSE_LOCAL_PATH),
                        ClickhouseFileCopyMethod.from(readonlyConfig.get(COPY_METHOD).getName()),
                        nodeUser,
                        readonlyConfig.get(NODE_FREE_PASSWORD),
                        nodePassword,
                        readonlyConfig.get(COMPATIBLE_MODE),
                        readonlyConfig.get(FILE_TEMP_PATH),
                        readonlyConfig.get(FILE_FIELDS_DELIMITER),
                        readonlyConfig.get(KEY_PATH));

View on GitHub (pinned to cf67b549a7)

Solutions

Set file_fields_delimiter to exactly one character, e.g. file_fields_delimiter = ","
For tab, use the actual tab escape recognized by the option parsing (check docs) so the resulting string length is 1
Trim any surrounding whitespace from the configured value

Example fix

// before
file_fields_delimiter = ", "
// after
file_fields_delimiter = ","

Defensive patterns

Strategy: validation

Validate before calling

String delim = config.get(FILE_FIELDS_DELIMITER);
if (delim == null || delim.length() != 1) {
    throw new IllegalArgumentException("file_fields_delimiter must be a single character, got: " + delim);
}

Prevention

Write the delimiter as a single literal character, not a multi-char escape
Trim whitespace from config values before submitting
Validate the HOCON config before job submission

When it happens

Trigger: Calling createSink with a ReadonlyConfig where FILE_FIELDS_DELIMITER has length != 1, e.g. `file_fields_delimiter = "\t"` written as literal two characters, `", "` (comma+space), or an escaped sequence like `\\t` that arrives as two characters.

Common situations: Users copy delimiters from docs where the tab is shown as the two-character escape `\\t`; copying a CSV example with a trailing space after the comma; pasting a delimiter with a hidden trailing whitespace.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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