What causes "error connecting to MongoDB: %w" in apache/beam?

Validate the connection URI format: mongodb://[user:pass@]host[:port]/[db][?options] or mongodb+srv://.

error connecting to MongoDB

Error message

error connecting to MongoDB: %w

What it means

Returned by newClient in mongodbio when mongo.Connect fails to establish a client from the given URI. Setup calls this during pipeline start, so the whole source/sink fails immediately. It wraps the underlying driver error.

Solutions

Validate the connection URI format: mongodb://[user:pass@]host[:port]/[db][?options] or mongodb+srv://.
Percent-encode special characters in username/password (e.g. @ -> %40).
Confirm the driver version supports the URI options used (e.g. +srv requires driver >= 1.x with DNS support).
Test the same URI with mongosh or a small Go snippet to isolate the invalid option.

Example fix

// before: raw password with special chars
uri := "mongodb://user:p@ssw0rd@host:27017/db"

// after: percent-encoded credentials
uri := "mongodb://user:p%40ssw0rd@host:27017/db"

Defensive patterns

Strategy: validation

Validate before calling

func validMongoURI(uri string) error {
    u, err := url.Parse(uri)
    if err != nil { return err }
    if u.Scheme != "mongodb" && u.Scheme != "mongodb+srv" { return fmt.Errorf("bad scheme %q", u.Scheme) }
    if u.Host == "" { return fmt.Errorf("missing host") }
    return nil
}

Try / catch

client, err := newClient(ctx, uri)
if err != nil {
    return fmt.Errorf("mongo setup failed for %q: %w", redactURI(uri), err)
}

Prevention

Store the MongoDB URI in config/flags, validated at startup with url.Parse.
Percent-encode username and password (url.UserPassword handles this).
Use the correct scheme (mongodb+srv for Atlas SRV records).
Smoke-test the URI with mongosh before deploying the pipeline.

When it happens

Trigger: Calling Setup (via newClient) with a malformed MongoDB connection URI, unknown scheme, or invalid options (e.g. bad replicaSet parameter).

Common situations: Typo'd URI in pipeline options; URL-special characters in password not percent-encoded; wrong scheme (mongodb vs mongodb+srv); driver version mismatch after upgrade.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/e22899443b6094ab. Report an issue: GitHub.

Appendix: source

Thrown at sdks/go/pkg/beam/io/mongodbio/common.go:61

		client, err := newClient(ctx, fn.URI)
		if err != nil {
			return err
		}

		fn.client = client
	}

	fn.collection = fn.client.Database(fn.Database).Collection(fn.Collection)

	return nil
}

func newClient(ctx context.Context, uri string) (*mongo.Client, error) {
	opts := options.Client().ApplyURI(uri)

	client, err := mongo.Connect(ctx, opts)
	if err != nil {
		return nil, fmt.Errorf("error connecting to MongoDB: %w", err)
	}

	if err := client.Ping(ctx, readpref.Primary()); err != nil {
		return nil, fmt.Errorf("error pinging MongoDB: %w", err)
	}

	return client, nil
}

func (fn *mongoDBFn) Teardown(ctx context.Context) error {
	if err := fn.client.Disconnect(ctx); err != nil {
		return fmt.Errorf("error disconnecting from MongoDB: %w", err)
	}

	return nil
}

type documentID struct {

View on GitHub (pinned to 12126d8942)