What causes "Checking catalog path %s exists exception." in apache/seatunnel?

Verify the filesystem URI in the catalog config is correct and reachable (e.g. hdfs dfs -ls ).

apache/seatunnel · critical · CatalogException

Checking catalog path %s exists exception.

Error message

Checking catalog path %s exists exception.

What it means

HudiCatalog.open verifies (and creates if needed) the filesystem directory that holds the catalog's databases. If checking fs.exists(tableParentDfsPath) throws an IOException, it is wrapped in this CatalogException with the path in the message. This usually means the configured warehouse/base path is unreachable or the filesystem is misconfigured.

Source

Thrown at seatunnel-connectors-v2/connector-hudi/src/main/java/org/apache/seatunnel/connectors/seatunnel/hudi/catalog/HudiCatalog.java:91

    private FileSystem fs;

    public HudiCatalog(String catalogName, Configuration hadoopConf, String tableParentDfsPathStr) {
        this.catalogName = catalogName;
        this.hadoopConf = hadoopConf;
        this.tableParentDfsPathStr = tableParentDfsPathStr;
        this.tableParentDfsPath = new Path(tableParentDfsPathStr);
    }

    @Override
    public void open() throws CatalogException {
        fs = HadoopFSUtils.getFs(tableParentDfsPathStr, hadoopConf);
        try {
            if (!fs.exists(tableParentDfsPath)) {
                log.info("Table dfs path not exists, will be created");
                fs.mkdirs(tableParentDfsPath);
            }
        } catch (IOException e) {
            throw new CatalogException(
                    String.format(
                            "Checking catalog path %s exists exception.", tableParentDfsPathStr),
                    e);
        }
        if (!databaseExists(getDefaultDatabase())) {
            TablePath defaultDatabase = TablePath.of(getDefaultDatabase(), "default");
            createDatabase(defaultDatabase, true);
        }
    }

    @Override
    public void close() throws CatalogException {
        try {
            if (fs != null) {
                fs.close();
            }
        } catch (Exception e) {
            log.info("Hudi catalog close error.", e);

View on GitHub (pinned to cf67b549a7)

Solutions

Verify the filesystem URI in the catalog config is correct and reachable (e.g. hdfs dfs -ls <path>).
Check credentials/keys for the object store (S3/OSS) are configured on the worker running the job.
Confirm HDFS NameNode is up and out of safe mode if using HDFS.
Inspect the wrapped IOException cause in the stack trace for the root filesystem error.
Use file:// explicitly for local testing to rule out cluster issues.

Example fix

// before
warehouse = "hdfs://wrong-namenode:8020/hudi"
// after
warehouse = "hdfs://namenode:8020/hudi"

Defensive patterns

Strategy: try-catch

Validate before calling

// probe the path before opening the catalog
org.apache.hadoop.fs.FileSystem fs = org.apache.hadoop.fs.FileSystem.get(
        new org.apache.hadoop.conf.Configuration());
if (!fs.exists(new org.apache.hadoop.fs.Path(warehouseUri))) {
    fs.mkdirs(new org.apache.hadoop.fs.Path(warehouseUri));
}

Try / catch

try {
    catalog.open();
} catch (CatalogException e) {
    Throwable root = e;
    while (root.getCause() != null) root = root.getCause();
    throw new RuntimeException("Catalog path unreachable, root cause: " + root.getMessage(), e);
}

Prevention

Test the warehouse URI from the worker host (hdfs dfs -ls / aws s3 ls) before submitting jobs.
Keep object-store credentials in a standard, worker-accessible location (core-site.xml, env, IAM role).
Unwrap the IOException cause to identify filesystem vs credential vs network errors.

When it happens

Trigger: Calling open() on a HudiCatalog whose tableParentDfsPath cannot be probed: HDFS NameNode unreachable, S3/OSS credentials missing or wrong, bad scheme in the catalog base path (e.g. hdfs:// vs file://), or network partition.

Common situations: HDFS cluster down or NameNode in safe mode; AWS/S3 credentials not present on the SeaTunnel worker; typo in warehouse path URI; Kerberos/auth failure surfaced as IOException.

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

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