apache/seatunnel · error · IllegalArgumentException

init file storage properties is empty

Error message

init file storage properties is empty

What it means

checkInitStorageProperties rejects initialization when the properties map passed to IMapFileStorage.initialize() is null or empty. The file-based IMap storage needs at least the business key and cluster name to locate its WAL directory, so empty properties are fatal at init time.

Solutions

  1. Add the required storage properties (business key and cluster name) to the engine storage config.
  2. Check that seatunnel.yaml actually contains the imap file storage section and was picked up by the running process.
  3. When initializing programmatically, populate the map with at least BUSINESS_KEY and CLUSTER_NAME before calling initialize.

Example fix

// before
Map<String, Object> props = new HashMap<>();
storage.initialize(props);
// after
Map<String, Object> props = new HashMap<>();
props.put("storage.businessKey", "seatunnel");
props.put("cluster.name", "seatunnel-cluster");
storage.initialize(props);
Defensive patterns

Strategy: validation

Validate before calling

if (properties == null || properties.isEmpty()) {
    throw new IllegalStateException("imap file storage properties must not be empty");
}

Try / catch

try { storage.initialize(props); } catch (IllegalArgumentException e) { /* fix seatunnel.yaml storage section and re-init */ }

Prevention

When it happens

Trigger: Calling IMapStorageFactory.create()/initialize() with a null or empty properties map — e.g. seatunnel.yaml storage stanza missing, or programmatic creation with new HashMap<>().

Common situations: Incomplete seatunnel.yaml map storage configuration section; environment-specific config file not deployed; copy-paste dropped the imap-storage block.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/a5fc977543239dba. 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:356

            try {
                if (requestFuture.isDone() || Boolean.TRUE.equals(requestFuture.get())) {
                    success = true;
                }
            } catch (Exception e) {
                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)