apache/seatunnel · error · IllegalArgumentException

${key} is required

Error message

${key} is required

What it means

PaimonCatalogLoader.checkConfiguration scans the Paimon Configuration for a required key and throws IllegalArgumentException "<key> is required" when the key is entirely absent. This enforces that mandatory Paimon settings (e.g. security or metastore properties) exist before the catalog is used.

Source

Thrown at seatunnel-connectors-v2/connector-paimon/src/main/java/org/apache/seatunnel/connectors/seatunnel/paimon/catalog/PaimonCatalogLoader.java:136

            return catalog;
        } catch (Exception e) {
            throw new PaimonConnectorException(
                    PaimonConnectorErrorCode.LOAD_CATALOG, e.getMessage(), e);
        }
    }

    void checkConfiguration(Configuration configuration, String key) {
        Iterator<Map.Entry<String, String>> entryIterator = configuration.iterator();
        while (entryIterator.hasNext()) {
            Map.Entry<String, String> entry = entryIterator.next();
            if (entry.getKey().equals(key)) {
                if (StringUtils.isBlank(entry.getValue())) {
                    throw new IllegalArgumentException("The value of" + key + " is required");
                }
                return;
            }
        }
        throw new IllegalArgumentException(key + " is required");
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add the missing key with a valid value to the Paimon configuration file referenced by paimon-conf-dir.
2. Verify the exact key spelling expected by the loader (string match, case-sensitive).
3. Ensure the conf directory/file is actually present and readable at runtime (mounted volume, packaged resource).
4. Check for version-specific property renames between your Paimon version and the connector's expectation.

Example fix

// before (paimon conf missing entry)
warehouse = hdfs://ns/paimon
// after
warehouse = hdfs://ns/paimon
security.kerberos.principal = etl_user@REALM

Set<String> required = Set.of("security.kerberos.principal");
for (String key : required) {
    if (!configuration.containsKey(key)) {
        throw new ConfigValidationException(key + " missing from paimon conf");
    }
}

try {
    loader.loadCatalog();
} catch (IllegalArgumentException e) {
    if (e.getMessage().endsWith(" is required")) {
        LOG.error("add missing paimon conf key: {}", e.getMessage());
    }
    throw e;
}

When it happens

Trigger: loadCatalog -> checkConfiguration(configuration, key) where the key does not appear at all in the loaded Paimon Configuration (paimon-conf files or programmatically built options), e.g. missing security.kerberos.principal in the conf.

Common situations: Fresh deployment where paimon conf was not copied/included; typo in the property name so the loader cannot find it; conf file not mounted into the container; renaming a property in a newer Paimon version.

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

• The value of${key} is required
• ${CommonError.convertToConnectorPropsBlankError(Paimon, prop
• ${key} is required
• ${key} is required
• Condition operator must not be null

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