apache/seatunnel · error · CatalogException

Error while checking whether table exists under path:${baseP

Error message

Error while checking whether table exists under path:${basePath}

What it means

HudiCatalog.tableExists() wraps IOException from checking for the .hoodie metadata folder and hoodie.properties file under the table base path. Existence is determined by the presence of these Hudi metadata files; a filesystem I/O failure is reported as a CatalogException rather than returning false, to avoid silently claiming a table does not exist.

Source

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

                    .map(fileStatus -> fileStatus.getPath().getName())
                    .collect(Collectors.toList());
        } catch (IOException e) {
            throw new CatalogException(
                    String.format("Listing table in database %s exception.", dbPath), e);
        }
    }

    @Override
    public boolean tableExists(TablePath tablePath) throws CatalogException {
        String basePath = inferTablePath(tableParentDfsPathStr, tablePath);
        try {
            return fs.exists(new Path(basePath, HoodieTableMetaClient.METAFOLDER_NAME))
                    && fs.exists(
                            new Path(
                                    new Path(basePath, HoodieTableMetaClient.METAFOLDER_NAME),
                                    HoodieTableConfig.HOODIE_PROPERTIES_FILE));
        } catch (IOException e) {
            throw new CatalogException(
                    "Error while checking whether table exists under path:" + basePath, e);
        }
    }

    @Override
    public CatalogTable getTable(TablePath tablePath)
            throws CatalogException, TableNotExistException {
        if (!tableExists(tablePath)) {
            throw new TableNotExistException(name(), tablePath);
        }
        HoodieTableMetaClient hoodieTableMetaClient =
                HoodieTableMetaClient.builder()
                        .setBasePath(inferTablePath(tableParentDfsPathStr, tablePath))
                        .setConf(HadoopFSUtils.getStorageConfWithCopy(hadoopConf))
                        .build();
        HoodieTableType tableType = hoodieTableMetaClient.getTableType();
        HoodieTableConfig tableConfig = hoodieTableMetaClient.getTableConfig();
        TableSchema tableSchema = convertSchema(TableSchema.builder(), tableConfig);

View on GitHub (pinned to cf67b549a7)

Solutions

Check filesystem availability and credentials; retry the call once the environment is healthy.
Verify the table path passed matches the actual Hudi table location (base path containing .hoodie/hoodie.properties).
Fix permission settings (Kerberos/login user) so the connector user can stat the path.
Inspect the wrapped IOException cause in the stack trace for the concrete storage error.

Defensive patterns

Strategy: try-catch

Validate before calling

// Java
org.apache.hadoop.fs.FileSystem fs = org.apache.hadoop.fs.FileSystem.get(conf);
boolean ok = fs.exists(new Path(basePath, ".hoodie/hoodie.properties"));

Try / catch

// Java
try {
    boolean exists = catalog.tableExists(tablePath);
} catch (CatalogException e) {
    Throwable c = e.getCause();
    if (c instanceof IOException) { /* storage issue: check creds, retry */ }
    throw e;
}

Prevention

Validate the table base path contains .hoodie/hoodie.properties before catalog operations.
Keep storage credentials refreshed for long-running jobs.
Use consistent table_parent_dfs_path so basePath inference is correct.
Treat false from tableExists and CatalogException differently: false = missing table, exception = storage problem.

When it happens

Trigger: Calling tableExists(tablePath) (directly or indirectly via getTable/dropTable) when fs.exists() on <basePath>/.hoodie/hoodie.properties throws IOException: filesystem unavailable, permission errors, or transient cloud-storage failures.

Common situations: S3/OSS throttling or expired credentials; HDFS NameNode hiccup; Kerberos/permission misconfiguration preventing path stat; wrong basePath derived from tableParentDfsPathStr so the path lookup fails.

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/b318a5a54afd3a6c. Report an issue: GitHub.