apache/beam · error

error executing collStats command: %w

Error message

error executing collStats command: %w

What it means

getCollectionSize runs the server-side collStats command (with primary read preference) to learn the collection's byte size, which bucketAutoSplits uses to decide how many buckets to create. When the RunCommand call or BSON decode fails, the error is wrapped as 'error executing collStats command'. This aborts the bucketAuto split strategy.

Source

Thrown at sdks/go/pkg/beam/io/mongodbio/id_range_split.go:64

	bucketCount := calculateBucketCount(collSize, bundleSize)

	buckets, err := getBuckets(ctx, collection, outerRange.Filter(), bucketCount)
	if err != nil {
		return nil, err
	}

	return idRangesFromBuckets(buckets, outerRange), nil
}

func getCollectionSize(ctx context.Context, collection *mongo.Collection) (int64, error) {
	cmd := bson.M{"collStats": collection.Name()}
	opts := options.RunCmd().SetReadPreference(readpref.Primary())

	var stats struct {
		Size int64 `bson:"size"`
	}
	if err := collection.Database().RunCommand(ctx, cmd, opts).Decode(&stats); err != nil {
		return 0, fmt.Errorf("error executing collStats command: %w", err)
	}

	return stats.Size, nil
}

func calculateBucketCount(totalSize int64, bundleSize int64) int32 {
	if bundleSize < 0 {
		panic("monogdbio.calculateBucketCount: bundle size must be greater than 0")
	}

	count := totalSize / bundleSize
	if totalSize%bundleSize != 0 {
		count++
	}

	if count > int64(maxBucketCount) {
		count = maxBucketCount
	}

View on GitHub (pinned to 12126d8942)

Solutions

1. Check the wrapped cause: authorization errors require granting collStats on the database
2. Verify connectivity to the primary (the command forces readpref.Primary)
3. Increase the context timeout for split planning if the deadline is being exceeded
4. Fall back to the splitVector or single-split strategy by configuring the splitter accordingly
5. Confirm server version supports collStats for the target namespace

Example fix

// before
client, err := mongo.Connect(ctx, options.Client().ApplyURI(uri)) // user without collStats
// after — grant role in mongo shell:
// db.grantRolesToUser("beamReader", [{role: "read", db: "mydb"}])
client, err := mongo.Connect(ctx, options.Client().ApplyURI(uri), options.Client().SetAuth(options.Credential{Username: "beamReader", Password: pwd}))

// check privileges ahead of time
var ok struct{ Ok int }
err := db.RunCommand(ctx, bson.D{{Key:"collStats", Value: coll.Name()}}).Decode(&ok)

size, err := getCollectionSize(ctx, coll)
if err != nil {
	return fallbackSplitStrategy(ctx, coll, r, n) // e.g. splitVector or single split
}

When it happens

Trigger: bucketAutoSplits calls getCollectionSize; collection.Database().RunCommand(ctx, {collStats: ...}) fails — server unavailable, command not authorized, context deadline exceeded, or the reply cannot be decoded into the stats struct.

Common situations: Connected user lacks the collStats privilege; MongoDB version or topology where the command is rejected; network interruption during split planning; context canceled by the runner before the command completes.

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

• error finding document ID to split on: %w
• error executing bucketAuto aggregation: %w
• error executing splitVector command: %w
• Restriction tracker missing.
• fraction must be between 0 and 1

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