apache/beam · error

batch size must be greater than 0

Error message

batch size must be greater than 0

What it means

WithWriteBatchSize is a WriteOption for the Beam MongoDB connector controlling how many documents are batched per MongoDB insert. It rejects values <= 0 since batching requires at least one document per batch. The error surfaces when options are applied to WriteOption.

Source

Thrown at sdks/go/pkg/beam/io/mongodbio/write_option.go:36

import (
	"errors"
)

// WriteOption represents options for writing to MongoDB.
type WriteOption struct {
	BatchSize int64
	Ordered   bool
}

// WriteOptionFn is a function that configures a WriteOption.
type WriteOptionFn func(option *WriteOption) error

// WithWriteBatchSize configures the WriteOption to use the provided batch size when writing
// documents.
func WithWriteBatchSize(batchSize int64) WriteOptionFn {
	return func(o *WriteOption) error {
		if batchSize <= 0 {
			return errors.New("batch size must be greater than 0")
		}

		o.BatchSize = batchSize
		return nil
	}
}

// WithWriteOrdered configures the WriteOption whether to apply an ordered bulk write.
func WithWriteOrdered(ordered bool) WriteOptionFn {
	return func(o *WriteOption) error {
		o.Ordered = ordered
		return nil
	}
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass a positive batch size, e.g. mongodbio.WithWriteBatchSize(1000).
2. Validate the configured value before building options and fall back to a sensible default (e.g. 500-1000 docs).
3. Fix upstream parsing so omitted config fields yield the default rather than 0.

Example fix

// before
opts = append(opts, mongodbio.WithWriteBatchSize(batchSize)) // batchSize = 0
// after
if batchSize <= 0 {
    batchSize = 1000
}
opts = append(opts, mongodbio.WithWriteBatchSize(batchSize))

if batchSize <= 0 {
    return fmt.Errorf("batchSize must be > 0, got %d", batchSize)
}
opts = append(opts, mongodbio.WithWriteBatchSize(batchSize))

if err := applyOptions(writeOpts...); err != nil {
    return fmt.Errorf("mongodbio write options invalid: %w", err)
}

When it happens

Trigger: Calling mongodbio.Write with options including mongodbio.WithWriteBatchSize(0) or any negative int64, e.g. from an unset or mis-parsed configuration value.

Common situations: Batch size sourced from an environment variable or pipeline option defaulting to 0; a config YAML/JSON field omitted and unmarshaled as zero; confusing batch size with bundle size options.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• bundle size must be greater than 0
• fraction must be between 0 and 1
• fetch size must be greater than 0
• start sequence number must be greater than 0
• end sequence number must be greater than 0

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