apache/seatunnel · error · CatalogException

Failed to list databases

Error message

Failed to list databases

What it means

MongodbCatalog.listDatabases() wraps any failure while iterating mongoClient.listDatabaseNames() into a CatalogException. This means the MongoDB server could not be contacted or the listDatabases command was rejected. The underlying cause is attached as the cause.

Source

Thrown at seatunnel-connectors-v2/connector-mongodb/src/main/java/org/apache/seatunnel/connectors/seatunnel/mongodb/catalog/MongodbCatalog.java:92

    @Override
    public boolean databaseExists(String databaseName) throws CatalogException {
        try {
            return listDatabases().contains(databaseName);
        } catch (Exception e) {
            throw new CatalogException("Failed to check database existence: " + databaseName, e);
        }
    }

    @Override
    public List<String> listDatabases() throws CatalogException {
        try {
            List<String> dbs = new ArrayList<>();
            for (String name : mongoClient.listDatabaseNames()) {
                dbs.add(name);
            }
            return dbs;
        } catch (Exception e) {
            throw new CatalogException("Failed to list databases", e);
        }
    }

    @Override
    public List<String> listTables(String databaseName)
            throws CatalogException, DatabaseNotExistException {
        if (!databaseExists(databaseName)) {
            throw new DatabaseNotExistException(name(), databaseName);
        }
        try {
            MongoDatabase db = mongoClient.getDatabase(databaseName);
            return db.listCollectionNames().into(new ArrayList<>());
        } catch (Exception e) {
            throw new CatalogException("Failed to list tables for database: " + databaseName, e);
        }
    }

    @Override

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Verify the catalog's mongodb connection URI and that the server is reachable (mongosh with the same URI).
  2. Check credentials in the URI and that the user has the necessary privilege (clusterMonitor / listDatabases on admin).
  3. Inspect the wrapped cause exception (getCause()) for the concrete driver error (timeout, auth, DNS).
  4. If using a replica set, ensure the seed list includes reachable members and the client can find the primary.
  5. Increase connectTimeout/socketTimeout options if the server is slow to respond.

Example fix

// before
List<String> dbs = catalog.listDatabases();
// after
try {
    List<String> dbs = catalog.listDatabases();
} catch (CatalogException e) {
    LOG.error("listDatabases failed: {}", e.getCause() != null ? e.getCause().getMessage() : e.getMessage(), e);
    throw e;
}
Defensive patterns

Strategy: try-catch

Validate before calling

// preflight connection check
try (MongoClient c = MongoClients.create(uri)) {
    c.listDatabaseNames().first(); // throws if unreachable/unauthorized
}

Try / catch

try {
    catalog.listDatabases();
} catch (CatalogException e) {
    // log e.getCause() (MongoTimeoutException / MongoSecurityException)
}

Prevention

When it happens

Trigger: Calling listDatabases() (directly or via databaseExists) when the MongoDB server is down, the host/port in the connection string is wrong, credentials are invalid, or the connected user lacks listDatabases privileges.

Common situations: Wrong mongodb:// connection URI in catalog options, MongoDB not yet started in Docker/dev, firewall or DNS failure, user missing clusterMonitor role on admin DB, replica set primary unavailable.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

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