apache/seatunnel · error · FileConnectorException

SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED

SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED

Error message

When sync_mode=update, file_format_type must be set.

What it means

validateUpdateSyncConfig enforces that when the file source runs in sync_mode=update (incremental synchronization), the plugin config must declare file_format_type. If the key is absent, a FileConnectorException with SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED is thrown during initialization.

Source

Thrown at seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/source/reader/AbstractReadStrategy.java:761

        if (targetHadoopFileSystemProxy != null && !shareTargetFileSystemProxy) {
            closeFileSystemProxy(targetHadoopFileSystemProxy, "target");
        }
        if (hadoopFileSystemProxy != null) {
            closeFileSystemProxy(hadoopFileSystemProxy, "source");
        }
    }

    private void closeFileSystemProxy(HadoopFileSystemProxy proxy, String role) {
        try {
            proxy.close();
        } catch (Exception e) {
            log.warn("Failed to close {} file system proxy", role, e);
        }
    }

    private void validateUpdateSyncConfig(Config pluginConfig) {
        if (!pluginConfig.hasPath(FileBaseSourceOptions.FILE_FORMAT_TYPE.key())) {
            throw new FileConnectorException(
                    SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED,
                    "When sync_mode=update, file_format_type must be set.");
        }
        FileFormat fileFormat =
                FileFormat.valueOf(
                        pluginConfig
                                .getString(FileBaseSourceOptions.FILE_FORMAT_TYPE.key())
                                .toUpperCase());
        if (fileFormat != FileFormat.BINARY) {
            throw new FileConnectorException(
                    SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED,
                    "sync_mode=update currently only supports file_format_type=binary.");
        }

        if (!pluginConfig.hasPath(FileBaseSourceOptions.TARGET_PATH.key())
                || StringUtils.isBlank(
                        pluginConfig.getString(FileBaseSourceOptions.TARGET_PATH.key()))) {
            throw new FileConnectorException(

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add file_format_type = "binary" to the source config (the only format update mode supports).
2. If incremental sync is not needed, remove sync_mode = update to use normal batch semantics.

Example fix

// before
sync_mode = update
// after
sync_mode = update
file_format_type = binary

if (config.hasPath("sync_mode") && "update".equals(config.getString("sync_mode")) && !config.hasPath("file_format_type")) {
    throw new IllegalArgumentException("sync_mode=update requires file_format_type");
}

try {
    submitJob(conf);
} catch (FileConnectorException e) {
    if (e.getSeaTunnelApiErrorCode() == SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED) {
        // fix config and resubmit
    }
}

When it happens

Trigger: Configuring a file source with sync_mode = update but omitting file_format_type; validation runs in AbstractReadStrategy during reader setup.

Common situations: Users copy a batch-mode file-source config and only add sync_mode = update, forgetting the format key the update mode requires to interpret files.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Schema config can not be empty
• Unknown format type:
• Option '${option}' cannot be blank
• Option '${valuesAndOptions[index + 1]}' is not valid for the
• Option 'field_delimiter' cannot be empty

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