apache/seatunnel · error · IllegalArgumentException

${key} is required

Error message

${key} is required

What it means

AbstractConfiguration.checkConfiguration validates that a config map contains a value for each required key; if a key is missing or maps to null it throws this IllegalArgumentException with '<key> is required'. Subclass buildConfiguration methods (e.g. HdfsConfiguration) call it before building the Hadoop Configuration.

Source

Thrown at seatunnel-engine/seatunnel-engine-storage/imap-storage-plugins/imap-storage-file/src/main/java/org/apache/seatunnel/engine/imap/storage/file/config/AbstractConfiguration.java:52

    public Long getBlockSize() {
        return blockSize;
    }

    public void setBlockSize(Long blockSize) {
        this.blockSize = blockSize;
    }

    /**
     * check the configuration keys
     *
     * @param config configuration
     * @param keys keys
     */
    void checkConfiguration(Map<String, String> config, String... keys) {
        for (String key : keys) {
            if (!config.containsKey(key) || null == config.get(key)) {
                throw new IllegalArgumentException(key + " is required");
            }
        }
    }

    public abstract Configuration buildConfiguration(Map<String, String> config)
            throws IMapStorageException;

    /**
     * set extra options for configuration
     *
     * @param hadoopConf
     * @param config
     * @param prefix
     */
    void setExtraConfiguration(
            Configuration hadoopConf, Map<String, String> config, String prefix) {
        config.forEach(
                (k, v) -> {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add the missing key named in the message to the storage config with a non-null value.
2. Check YAML indentation so keys are nested under the correct map section.
3. Ensure placeholder substitution (env vars) actually resolves — a ${VAR} that is unset can yield null.

Example fix

// before
storage:
  hdfs:
    url: "hdfs://nn:8020"
// after (message said principal is required)
storage:
  hdfs:
    url: "hdfs://nn:8020"
    kerberosPrincipal: "st/_HOST@EXAMPLE.COM"
    kerberosKeytabFilePath: "/etc/security/keytabs/st.keytab"

java.util.Map<String,String> cfg = /* parsed storage config */;
java.util.List<String> required = java.util.Arrays.asList("url", "kerberosPrincipal", "kerberosKeytabFilePath");
required.forEach(k -> { if (cfg.get(k) == null) throw new IllegalStateException(k + " missing in storage config"); });

try { Configuration c = hdfsConfiguration.buildConfiguration(config); } catch (IllegalArgumentException e) { /* key named in message; add it with a non-null value */ }

When it happens

Trigger: Calling buildConfiguration() with a config map lacking e.g. hdfs name/kerberos keys, or containing the key with an explicit null value.

Common situations: seatunnel.yaml storage section missing kerberos principal/keytab or hdfs URL entries; YAML indentation dropping keys; keys provided as environment placeholders that resolved to null.

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

• ${key} is required
• ${key} is required
• Condition operator must not be null
• AmazonDocumentDB option '' must not be blank
• AmazonDocumentDB option '' must be a valid BSON/JSON documen

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