apache/seatunnel · error · IllegalArgumentException

${CONNECTOR_JAR_HA_STORAGE_TYPE} must in [localfile, hdfs]

Error message

${CONNECTOR_JAR_HA_STORAGE_TYPE} must in [localfile, hdfs]

What it means

Thrown by the Zeta master node config parser when the 'connector_jar_ha_storage_type' option is present but its value is not one of the two supported HA storage backends, 'localfile' or 'hdfs'. The parser validates the raw config string against a whitelist before assigning it to the connector-jar HA storage configuration, failing fast with an IllegalArgumentException on any other value.

Source

Thrown at seatunnel-engine/seatunnel-engine-common/src/main/java/org/apache/seatunnel/engine/common/config/YamlSeaTunnelDomConfigProcessor.java:515

            } else {
                LOGGER.warning("Unrecognized element: " + name);
            }
        }
        return connectorJarStorageConfig;
    }

    private ConnectorJarHAStorageConfig parseConnectorJarHAStorageConfig(
            Node connectorJarHAStorageConfigNode) {
        ConnectorJarHAStorageConfig connectorJarHAStorageConfig = new ConnectorJarHAStorageConfig();
        for (Node node : childElements(connectorJarHAStorageConfigNode)) {
            String name = cleanNodeName(node);
            if (ServerConfigOptions.MasterServerConfigOptions.CONNECTOR_JAR_HA_STORAGE_TYPE
                    .key()
                    .equals(name)) {
                String type = getTextContent(node);
                if (StringUtils.isNotBlank(type)
                        && !Arrays.asList("localfile", "hdfs").contains(type)) {
                    throw new IllegalArgumentException(
                            ServerConfigOptions.MasterServerConfigOptions
                                            .CONNECTOR_JAR_HA_STORAGE_TYPE
                                    + " must in [localfile, hdfs]");
                }
                connectorJarHAStorageConfig.setType(type);
            } else if (ServerConfigOptions.MasterServerConfigOptions
                    .CONNECTOR_JAR_HA_STORAGE_PLUGIN_CONFIG
                    .key()
                    .equals(name)) {
                Map<String, String> connectorJarHAStoragePluginConfig =
                        parseConnectorJarHAStoragePluginConfig(node);
                connectorJarHAStorageConfig.setStoragePluginConfig(
                        connectorJarHAStoragePluginConfig);
            } else {
                LOGGER.warning("Unrecognized element: " + name);
            }
        }
        return connectorJarHAStorageConfig;

View on GitHub (pinned to cf67b549a7)

Solutions

1. Set connector_jar_ha_storage_type to exactly 'localfile' or 'hdfs' (lowercase) in seatunnel.yaml.
2. Remove the option entirely to fall back to the default storage type if HA connector-jar storage is not needed.
3. If HDFS storage is intended, verify the paired connector-jar-storage HDFS options (fs default name, etc.) are also configured.

Example fix

# before
connector_jar_ha_storage_type = HDFS
# after
connector_jar_ha_storage_type = hdfs

Set<String> allowed = Set.of("localfile", "hdfs");
String v = yaml.getString("connector_jar_ha_storage_type");
if (v != null && !allowed.contains(v)) throw new IllegalArgumentException("connector_jar_ha_storage_type must be localfile or hdfs, got: " + v);

When it happens

Trigger: Starting a Zeta master node with seatunnel.yaml containing connector_jar_ha_storage_type set to a misspelled or unsupported value (e.g. 'LocalFile', 's3', 'oss', or a trailing space).

Common situations: Users copy HDFS/S3 examples from other SeaTunnel options and assume other storage plugins work here; typos or case-mismatched values like 'HDFS' instead of 'hdfs'.

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

• 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/b42d1c952b42e412. Report an issue: GitHub.