apache/beam · error

error finding document ID to split on: %w

Error message

error finding document ID to split on: %w

What it means

FractionSplits uses findID to locate a document ID near the midpoint of the restriction so the id-range can be split for dynamic work rebalancing. If that find command fails for any reason other than mongo.ErrNoDocuments, the error is wrapped as 'error finding document ID to split on'. It means the split probe query against the collection failed, not that the range is unsplittable.

Source

Thrown at sdks/go/pkg/beam/io/mongodbio/id_range_restriction.go:127

	return restrictionsFromIDRanges(ctx, collection, idRanges, r.CustomFilter), err
}

// FractionSplits divides the restriction into a lower and higher ID sub-restriction based on the
// desired fraction of work the lower piece should be responsible for.
func (r idRangeRestriction) FractionSplits(
	ctx context.Context,
	collection *mongo.Collection,
	fraction float64,
) (lower, higher idRangeRestriction, err error) {
	skip := int64(math.Round(float64(r.Count) * fraction))

	splitID, err := findID(ctx, collection, r.Filter(), 1, skip)
	if err != nil {
		if errors.Is(err, mongo.ErrNoDocuments) {
			return idRangeRestriction{}, idRangeRestriction{}, nil
		}

		return idRangeRestriction{}, idRangeRestriction{}, fmt.Errorf(
			"error finding document ID to split on: %w",
			err,
		)
	}

	lower = idRangeRestriction{
		IDRange: idRange{
			Min:          r.IDRange.Min,
			MinInclusive: r.IDRange.MinInclusive,
			Max:          splitID,
			MaxInclusive: false,
		},
		CustomFilter: r.CustomFilter,
		Count:        skip,
	}

	higher = idRangeRestriction{
		IDRange: idRange{

View on GitHub (pinned to 12126d8942)

Solutions

1. Read the wrapped cause; if it is a query error, verify the restriction's filter document is valid for the collection
2. Check MongoDB server health and network stability; transient errors usually resolve on the next split attempt
3. Validate that the filter's field types match the stored documents (e.g. string vs ObjectId for _id)
4. Confirm the user has find permission on the collection
5. Retry the pipeline; FractionSplits failures during rebalancing are often transient

Example fix

// before — filter built with wrong id type
filter := bson.M{"_id": 12345}
// after — match stored ObjectId type
id, _ := primitive.ObjectIDFromHex("652f1a...")
filter := bson.M{"_id": id}

// validate the filter round-trips as BSON and matches at least one doc
if err := collection.FindOne(ctx, r.Filter()).Err(); err != nil && !errors.Is(err, mongo.ErrNoDocuments) {
	return err
}

if _, err := split(ctx, r); err != nil {
	if !errors.Is(err, context.Canceled) {
		log.Printf("fraction split failed, continuing unsplit: %v", err)
	}
}

When it happens

Trigger: Beam calls FractionSplits to split a mongodbio read restriction; the internal find command (sort by _id, skip near the middle, limit 1) fails due to network error, server error, query failure, or a bad filter document.

Common situations: MongoDB server restarted or connection dropped while the pipeline runs; a user-supplied filter that the server rejects (invalid BSON operator, type mismatch on _id); sharded cluster returning a transient error during a rebalance request.

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 executing collStats command: %w
• error executing bucketAuto aggregation: %w
• error executing splitVector command: %w
• error executing find command: %w
• Restriction tracker missing.

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