apache/seatunnel · error · IMapStorageException

load all keys error parent path is ${businessRootPath}

Error message

load all keys error parent path is ${businessRootPath}

What it means

loadAllKeys() enumerates WAL keys under businessRootPath via WALReader.loadAllKeys; an IOException there is wrapped in this IMapStorageException. It indicates the key index tree under the business root path could not be listed/read.

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:250

    }

    @Override
    public Map<Object, Object> loadAll() {
        try {
            WALReader reader = new WALReader(fs, fileConfiguration, serializer);
            return reader.loadAllData(new Path(businessRootPath), new HashSet<>());
        } catch (IOException e) {
            throw new IMapStorageException("load all data error", e);
        }
    }

    @Override
    public Set<Object> loadAllKeys() {
        try {
            WALReader reader = new WALReader(fs, fileConfiguration, serializer);
            return reader.loadAllKeys(new Path(businessRootPath));
        } catch (IOException e) {
            throw new IMapStorageException(
                    e, "load all keys error parent path is {}", e, businessRootPath);
        }
    }

    @Override
    public void destroy(boolean deleteAllFileFlag) {
        log.info(
                "start destroy IMapFileStorage, businessName is {}, cluster name is {}",
                businessName,
                region);
        /**
         * 1. close current disruptor 2. delete all files notice: we can not delete the files in the
         * middle of the write, so some current file may be not deleted
         */
        try {
            walDisruptor.close();
        } catch (IOException e) {
            log.error("close walDisruptor error", e);

View on GitHub (pinned to cf67b549a7)

Solutions

1. Verify businessRootPath exists and list it manually (hdfs dfs -ls <businessRootPath>).
2. Check HDFS connectivity and NameNode health.
3. Confirm read permissions for the engine's user on the path.
4. Recover or re-create the storage directory if it was deleted (see destroy/init flow).
5. Retry on transient IOExceptions.

Example fix

// before
throw new IMapStorageException(e, "load all keys error parent path is {}", e, businessRootPath);
// after (ensure path exists first)
if (!fs.exists(new Path(businessRootPath))) {
    return new HashSet<>();
}
return reader.loadAllKeys(new Path(businessRootPath));

if (!fs.exists(new org.apache.hadoop.fs.Path(businessRootPath))) {
    throw new IllegalStateException("WAL root path missing: " + businessRootPath);
}

try { Set<Object> keys = storage.loadAllKeys(); } catch (IMapStorageException e) { /* inspect cause IOException: exists? permissions? retry */ }

When it happens

Trigger: Calling IMapFileStorage.loadAllKeys() when businessRootPath is missing, HDFS listing fails (NameNode unreachable, permission denied), or WAL key files are unreadable/corrupt.

Common situations: Storage directory wiped between engine restarts; HDFS permissions changed after Kerberos user switch; flaky network to HDFS during cluster recovery.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Failed to list files from names${path}
• Failed to get file system
• load all data error
• FILE_LIST_GET_FAILED
• Failed during target_bulk_listing for path=%s

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