apache/seatunnel · error · CatalogException

Listing table in database %s exception.

Error message

Listing table in database %s exception.

What it means

HudiCatalog.listTables() wraps any IOException raised while listing directories under the database path on the Hadoop filesystem. The catalog treats each subdirectory of the database directory as a table, so a failure to read the directory listing aborts table discovery. The IOException is rethrown as a CatalogException with the database path in the message.

Source

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

            throw new CatalogException("Listing database exception.", e);
        }
    }

    @Override
    public List<String> listTables(String databaseName)
            throws CatalogException, DatabaseNotExistException {
        if (!databaseExists(databaseName)) {
            throw new DatabaseNotExistException(catalogName, databaseName);
        }

        Path dbPath = new Path(tableParentDfsPath, databaseName);
        try {
            return Arrays.stream(fs.listStatus(dbPath))
                    .filter(FileStatus::isDirectory)
                    .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);
        }
    }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Verify the database directory exists on the configured filesystem (hdfs dfs -ls / hadoop fs -ls on table_parent_dfs_path/<db>) and create it if missing.
2. Check filesystem connectivity and credentials (core-site.xml/hdfs-site.xml on classpath, cloud storage access keys, endpoint).
3. Retry once transient errors (NameNode safemode, S3 throttling) are resolved.
4. Confirm the catalog's table_parent_dfs_path option points to the root that actually contains your databases.

Example fix

// before
List<String> tables = catalog.listTables("mydb");
// after
if (!catalog.databaseExists("mydb")) {
    catalog.createDatabase(TablePath.of("mydb", "t"), true);
}
List<String> tables = catalog.listTables("mydb");

// Java
if (!catalog.databaseExists(dbName)) {
    catalog.createDatabase(TablePath.of(dbName, "t"), true);
}
FileSystem fs = FileSystem.get(conf);
if (!fs.exists(dbPath)) { /* create or abort */ }

// Java
try {
    tables = catalog.listTables(dbName);
} catch (CatalogException e) {
    if (e.getCause() instanceof IOException) {
        // check storage health, then retry
    } else throw e;
}

When it happens

Trigger: Calling listTables(databaseName) (directly or via catalog.tables()) when the underlying distributed filesystem (HDFS/S3/OSS) throws IOException on fs.listStatus(dbPath): NameNode unreachable, S3 throttling/credentials failure, or dbPath missing on the filesystem.

Common situations: HDFS NameNode in safemode or down; cloud storage credentials expired; database directory deleted manually or never created because createDatabase was skipped; wrong table parent DFS path configured (table_parent_dfs_path).

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

• Circular condition chain detected: '%s' already exists in th
• Condition for option '%s' has a null operator
• SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED
• Checking catalog path %s exists exception.
• Listing database exception.

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