apache/seatunnel · error · IllegalArgumentException

init file storage properties is not contains

Error message

init file storage properties is not contains ${requiredProperty}

What it means

checkInitStorageProperties requires the properties map passed to initialize() to contain both BUSINESS_KEY and CLUSTER_NAME; if either key is absent this IllegalArgumentException is thrown naming the missing property. The missing value is needed to build the WAL root path for the business data.

Solutions

1. Add the exact missing key named in the message (business key and/or cluster name) to the storage properties.
2. Compare your config against the documented property names — they are case-sensitive.
3. Validate config before engine start by pre-checking the map in deployment scripts.

Example fix

// before
props.put("cluster", "prod"); // wrong key
// after
props.put("cluster.name", "prod");

java.util.List<String> required = java.util.Arrays.asList("storage.businessKey", "cluster.name");
for (String k : required) {
    if (!properties.containsKey(k) || properties.get(k) == null) {
        throw new IllegalStateException("missing storage property: " + k);
    }
}

try { storage.initialize(props); } catch (IllegalArgumentException e) { /* message names the missing key; add it and re-init */ }

When it happens

Trigger: Calling initialize() with a properties map that lacks the business key or the cluster name entry — e.g. partial YAML config or typo'd property name.

Common situations: Property renamed/typo'd in seatunnel.yaml (case-sensitive keys); upgrade where storage config keys changed; hand-written programmatic init missing one of the two keys.

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

• init file storage properties is empty
• is required
• is required
• is required
• Agent config file not found

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

Appendix: source

Thrown at seatunnel-engine/seatunnel-engine-storage/imap-storage-plugins/imap-storage-file/src/main/java/org/apache/seatunnel/engine/imap/storage/file/IMapFileStorage.java:361

                log.error("wait for write status error", e);
            } finally {
                RequestFutureCache.remove(entry.getKey());
            }
            if (!success) {
                failures.add(entry.getValue());
            }
        }
        return failures;
    }

    private void checkInitStorageProperties(Map<String, Object> properties) {
        if (properties == null || properties.isEmpty()) {
            throw new IllegalArgumentException("init file storage properties is empty");
        }
        List<String> requiredProperties = Arrays.asList(BUSINESS_KEY, CLUSTER_NAME);
        for (String requiredProperty : requiredProperties) {
            if (!properties.containsKey(requiredProperty)) {
                throw new IllegalArgumentException(
                        "init file storage properties is not contains " + requiredProperty);
            }
        }
    }
}

View on GitHub (pinned to cf67b549a7)