apache/beam · error

error executing splitVector command: %w

Error message

error executing splitVector command: %w

What it means

getSplitKeys runs the splitVector database command on the admin/database to compute _id split points for a collection. When RunCommand fails to execute or decode, the error is wrapped as 'error executing splitVector command'. splitVector is typically restricted (often to mongos/admin contexts), so this commonly indicates an unsupported or unauthorized command.

Source

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

) ([]documentID, error) {
	database := collection.Database()
	namespace := fmt.Sprintf("%s.%s", database.Name(), collection.Name())

	cmd := bson.D{
		{Key: "splitVector", Value: namespace},
		{Key: "keyPattern", Value: bson.D{{Key: "_id", Value: 1}}},
		{Key: "min", Value: bson.D{{Key: "_id", Value: outerRange.Min}}},
		{Key: "max", Value: bson.D{{Key: "_id", Value: outerRange.Max}}},
		{Key: "maxChunkSizeBytes", Value: maxChunkSizeBytes},
	}

	opts := options.RunCmd().SetReadPreference(readpref.Primary())

	var result struct {
		SplitKeys []documentID `bson:"splitKeys"`
	}
	if err := database.RunCommand(ctx, cmd, opts).Decode(&result); err != nil {
		return nil, fmt.Errorf("error executing splitVector command: %w", err)
	}

	return result.SplitKeys, nil
}

func idRangesFromSplits(splitKeys []documentID, outerRange idRange) []idRange {
	subRanges := make([]idRange, len(splitKeys)+1)

	for i := 0; i < len(splitKeys)+1; i++ {
		subRange := idRange{}

		if i == 0 {
			subRange.Min = outerRange.Min
			subRange.MinInclusive = outerRange.MinInclusive
		} else {
			subRange.Min = splitKeys[i-1].ID
			subRange.MinInclusive = true
		}

View on GitHub (pinned to 12126d8942)

Solutions

1. Check the wrapped cause for an 'unauthorized'/'command not found' server error and fall back to the bucketAuto strategy
2. Grant the user the necessary role (splitVector is usually admin/sharding-only)
3. Verify the namespace and keyPattern passed to splitVector are correct
4. Ensure the command targets a mongos or shard that permits splitVector; avoid it on restricted managed services
5. Retry if the cause is a transient network error

Example fix

// before — Atlas user cannot run splitVector
splits, err := splitVectorSplits(ctx, db, coll, r, n, bundle)
// after — choose bucketAuto fallback when splitVector is rejected
if strings.Contains(err.Error(), "not authorized") {
	splits, err = bucketAutoSplits(ctx, coll, r, n, bundle)
}

// probe splitVector availability
err := db.RunCommand(ctx, bson.D{{Key:"splitVector", Value: ns}, {Key:"keyPattern", Value: bson.M{"_id":1}}, {Key:"maxChunkSizeBytes", Value:1}}).Err()

splits, err := splitVectorSplits(ctx, db, coll, r, n, bundle)
if err != nil {
	splits, err = bucketAutoSplits(ctx, coll, r, n, bundle)
}

When it happens

Trigger: splitVectorSplits calls getSplitKeys; database.RunCommand(ctx, {splitVector: ...}) fails — the command is not available on the target topology (e.g. standalone replica member via certain drivers/versions), the user lacks permission, maxChunkSizeBytes arg is invalid, or a network/context failure occurs.

Common situations: Running against standalone or Atlas instances where splitVector is not permitted for regular users; insufficient privileges (command normally reserved for sharding internals); wrong namespace or key pattern in the command; context deadline exceeded.

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 collStats command: %w
• error executing bucketAuto aggregation: %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/9bd6eed51cac2b2f. Report an issue: GitHub.