risingwavelabs/risingwave · error · SinkError::Mongodb

failed to send hello command to mongodb

Error message

failed to send hello command to mongodb

What it means

During `validate`, the sink sends a `hello` command to the `admin` database to verify the MongoDB server is reachable before the sink starts. If the command fails (connection error, auth failure, DNS failure), the error is wrapped with this context. It fails sink creation early rather than failing later at write time.

Source

Thrown at src/connector/src/sink/mongodb.rs:328

            }
        }

        if let Err(err) = self.config.common.collection_name.parse::<Namespace>() {
            return Err(SinkError::Config(anyhow!(err).context(format!(
                "invalid collection.name {}",
                self.config.common.collection_name
            ))));
        }

        // checking reachability
        let client = self.config.common.build_client().await?;
        let client = ClientGuard::new(self.param.sink_name.clone(), client);
        client
            .database("admin")
            .run_command(doc! {"hello":1})
            .await
            .map_err(|err| {
                SinkError::Mongodb(anyhow!(err).context("failed to send hello command to mongodb"))
            })?;

        if self.config.drop_collection_name_field && self.config.collection_name_field.is_none() {
            return Err(SinkError::Config(anyhow!(
                "collection.name.field must be specified when collection.name.field.drop is enabled"
            )));
        }

        // checking dynamic collection name settings
        if let Some(coll_field) = &self.config.collection_name_field {
            let fields = self.schema.fields();

            let coll_field_index = fields
                .iter()
                .enumerate()
                .find_map(|(index, field)| {
                    if &field.name == coll_field {
                        Some(index)

View on GitHub (pinned to 6469eb736d)

Solutions

  1. Verify the `url` option points to a reachable MongoDB instance (test with `mongosh <url>` from the same host/network as RisingWave).
  2. Check network/firewall/allowlist rules (e.g., Atlas IP access list, VPC peering, security groups).
  3. Confirm credentials in the URL are current and URL-encoded; check the wrapped mongodb error for the specific cause.
  4. If using SRV (`mongodb+srv://`), ensure DNS SRV resolution works from the RisingWave host.
Defensive patterns

Strategy: try-catch

Validate before calling

// Reachability precheck from the same network as RisingWave
const { MongoClient } = require('mongodb');
const c = new MongoClient(url, { serverSelectionTimeoutMS: 5000 });
await c.db('admin').command({ hello: 1 }); await c.close();

Try / catch

try {
  await createMongodbSink(options);
} catch (e) {
  if (String(e).includes("failed to send hello command to mongodb")) {
    // inspect cause: DNS, auth, timeout — fix url/credentials/firewall
  }
  throw e;
}

Prevention

When it happens

Trigger: Creating a mongodb sink when the server URL is wrong, the cluster is down, network/firewall blocks the port, TLS fails, or credentials are invalid (auth errors surface on the first command).

Common situations: Typo in `mongodb://` URL or wrong port; RisingWave cannot reach a VPC/internal Mongo cluster; Atlas requires IP allowlisting; expired/rotated credentials.

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 risingwavelabs/risingwave@6469eb736d (2026-09-11). Data as JSON: /api/errors/a2ac0cfa17e58614. Report an issue: GitHub.