apache/seatunnel · error · ClickhouseConnectorException

COMMON_ILLEGAL_ARGUMENT

COMMON_ILLEGAL_ARGUMENT

Error message

Unknown ClickhouseFileCopyMethod: 

What it means

ClickhouseFileCopyMethod.from(name) resolves the user-supplied file_copy_method option string into the enum by case-insensitive comparison. If no enum constant matches, it throws ClickhouseConnectorException with code COMMON_ILLEGAL_ARGUMENT naming the bad value. The valid values are the names declared by the enum (e.g. upload, s3, scp...).

Source

Thrown at seatunnel-connectors-v2/connector-clickhouse/src/main/java/org/apache/seatunnel/connectors/seatunnel/clickhouse/config/ClickhouseFileCopyMethod.java:44

    ;
    private final String name;

    ClickhouseFileCopyMethod(String name) {
        this.name = name;
    }

    public String getName() {
        return name;
    }

    public static ClickhouseFileCopyMethod from(String name) {
        for (ClickhouseFileCopyMethod clickhouseFileCopyMethod :
                ClickhouseFileCopyMethod.values()) {
            if (clickhouseFileCopyMethod.getName().equalsIgnoreCase(name)) {
                return clickhouseFileCopyMethod;
            }
        }
        throw new ClickhouseConnectorException(
                CommonErrorCodeDeprecated.ILLEGAL_ARGUMENT,
                "Unknown ClickhouseFileCopyMethod: " + name);
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Set file_copy_method to one of the exact enum names (check ClickhouseFileCopyMethod for the current valid set).
2. Fix typos and strip surrounding whitespace from the config value.
3. If migrating from an older version, map the old method name to its current enum name.
4. Wrap option parsing so a ClickhouseConnectorException surfaces the accepted values in the error message for the user.

Example fix

// before
file_copy_method = "S3cp"
// after
file_copy_method = "s3"

Set<String> valid = Arrays.stream(ClickhouseFileCopyMethod.values()).map(ClickhouseFileCopyMethod::getName).collect(Collectors.toSet());
if (!valid.contains(name.trim())) { throw new IllegalArgumentException("file_copy_method must be one of " + valid); }

try { method = ClickhouseFileCopyMethod.from(rawName.trim()); } catch (ClickhouseConnectorException e) { log.error("Invalid file_copy_method '{}'; valid values: {}", rawName, Arrays.toString(ClickhouseFileCopyMethod.values())); throw e; }

When it happens

Trigger: Setting the ClickHouse file connector option 'file_copy_method' (or passing a name to ClickhouseFileCopyMethod.from) with a value that does not match any enum constant's name, e.g. a typo like 'S3 ' or 's3cp', or an old/renamed method name.

Common situations: Config typo in the HOCON job file; copying an option value from another connector that uses different method names; upgrading SeaTunnel where a method name changed; whitespace or casing mistakes in hand-written configs.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Retry times must be greater than 0
• Unknown format type:
• not support this type of bufferType: ${bufferType}
• CLICKHOUSE_GET_TABLE_LIST_CONFIG_ERROR
• `table_path` and `sql` parameter cannot be both empty.

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