apache/seatunnel · critical · IllegalStateException

Failed to open AmazonDocumentDB source reader for database [

Error message

Failed to open AmazonDocumentDB source reader for database [%s], collection [%s]

What it means

AmazonDocumentDBSourceReader.open establishes the MongoDB client and resolves the configured database/collection when the reader starts. If any exception occurs while creating the client or getting the collection, the reader closes its resources and rethrows as IllegalStateException with the database and collection names, failing task initialization.

Source

Thrown at seatunnel-connectors-v2/connector-amazondocumentdb/src/main/java/org/apache/seatunnel/connectors/seatunnel/amazondocumentdb/source/AmazonDocumentDBSourceReader.java:83

    public AmazonDocumentDBSourceReader(
            Context context, AmazonDocumentDBConfig config, SeaTunnelRowType rowType) {
        this.context = context;
        this.config = config;
        this.deserializer = new DocumentDBItemDeserializer(rowType);
    }

    /** Opens the client once per reader so its connector-local TLS context has reader scope. */
    @Override
    public void open() {
        try {
            client = createMongoClient();
            collection =
                    client.getDatabase(config.getDatabase())
                            .getCollection(config.getCollection(), BsonDocument.class);
        } catch (Exception e) {
            close();
            throw new IllegalStateException(
                    String.format(
                            "Failed to open AmazonDocumentDB source reader for database [%s], collection [%s]",
                            config.getDatabase(), config.getCollection()),
                    e);
        }
    }

    /** Closes the cursor before the client to release the server-side query promptly. */
    @Override
    public void close() {
        closeCursor();
        if (client != null) {
            client.close();
            client = null;
        }
    }

    /**

View on GitHub (pinned to cf67b549a7)

Solutions

Verify connectivity to the DocumentDB endpoint (network, VPC/security groups, port 27017) and that the cluster is available.
Check the connection string/credentials in the source config, including TLS settings required by DocumentDB.
Confirm the database and collection names exist (db.getCollectionNames() in mongo shell).
Inspect the cause chain (e) for the root driver exception (e.g. MongoTimeoutException, MongoSecurityException).

Example fix

// before
url = "mongodb://wrong-host:27017"
// after: correct DocumentDB endpoint with TLS
url = "mongodb://user:pass@my-docdb.cluster-xxx.us-east-1.docdb.amazonaws.com:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0"

Defensive patterns

Strategy: try-catch

Validate before calling

try (MongoClient probe = MongoClients.create(connectionString)) {
    probe.getDatabase(dbName).runCommand(new BsonDocument("ping", new BsonInt32(1)));
} // run before submitting the job

Type guard

null

Try / catch

try { reader.open(); } catch (IllegalStateException e) { log.error("DocDB open failed: {}", e.getCause(), e); throw e; } // inspect e.getCause() for MongoTimeoutException/MongoSecurityException

Prevention

Verify endpoint, credentials, and TLS CA bundle before launching the job.
Confirm the DocumentDB cluster is in the same VPC/security-group-reachable from workers.
Validate database/collection names with the mongo shell first.

When it happens

Trigger: createMongoClient() fails (bad host/port, DNS, TLS, invalid credentials, driver classpath problem) or getDatabase(...).getCollection(...) throws; any Exception during open() triggers this wrapped error.

Common situations: Wrong connection string or DocumentDB endpoint in config; unreachable DocumentDB (security group/VPC, cluster not in 'available' state); missing TLS truststore for DocumentDB's required TLS; wrong username/password; typo in database or collection name.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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