Params: at least one of BatchSize or BatchSizeBytes must be…

Error message

Params: at least one of BatchSize or BatchSizeBytes must be > 0

What it means

Error returned by batch.Params.validate (used by GroupIntoBatches and GroupIntoBatchesWithShardedKey) when both BatchSize and BatchSizeBytes are zero (and neither is negative, which is checked earlier). With both triggers disabled the batch transform would never emit, so at least one positive bound is mandatory.

Solutions

Set BatchSize to a positive value (e.g. Params{BatchSize: 100})
Or set BatchSizeBytes to a positive byte limit (e.g. Params{BatchSizeBytes: 1 << 20})
Or set both for combined count/byte batching
Check config loading so defaults actually populate a nonzero size

Example fix

// before
p := batch.Params{MaxBufferingDuration: 10 * time.Second} // both sizes 0
// after
p := batch.Params{BatchSize: 100, MaxBufferingDuration: 10 * time.Second}

Defensive patterns

Strategy: validation

Validate before calling

if p.BatchSize == 0 && p.BatchSizeBytes == 0 { return errors.New("set BatchSize or BatchSizeBytes") } // before calling GroupIntoBatches

Try / catch

if err := p.Validate(); err != nil {
    return fmt.Errorf("invalid batch params: %w", err)
}

Prevention

Never pass a zero-value batch.Params struct
Remember MaxBufferingDuration alone does not satisfy batching
Provide defaults from config: BatchSize or BatchSizeBytes must be > 0
Write a constructor/helper that enforces at least one size is set

When it happens

Trigger: Passing batch.Params{} or Params with both BatchSize and BatchSizeBytes equal to 0 to GroupIntoBatches / GroupIntoBatchesWithShardedKey — e.g. a zero-value struct with only MaxBufferingDuration set.

Common situations: Forgetting to fill in Params (using the zero value), relying solely on MaxBufferingDuration thinking it alone triggers batching, or defaults read as 0 from an empty config.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at sdks/go/pkg/beam/transforms/batch/batch.go:189

	// would exceed BatchSizeBytes. Zero disables the byte-based
	// trigger.
	BatchSizeBytes int64

	// MaxBufferingDuration, when > 0, triggers emission of a partial
	// batch after this much processing time has elapsed since the
	// first element of the current batch was buffered.
	MaxBufferingDuration time.Duration
}

func (p Params) validate() error {
	if p.BatchSize < 0 {
		return fmt.Errorf("Params.BatchSize must be >= 0; got %d", p.BatchSize)
	}
	if p.BatchSizeBytes < 0 {
		return fmt.Errorf("Params.BatchSizeBytes must be >= 0; got %d", p.BatchSizeBytes)
	}
	if p.BatchSize == 0 && p.BatchSizeBytes == 0 {
		return fmt.Errorf("Params: at least one of BatchSize or BatchSizeBytes must be > 0")
	}
	if p.MaxBufferingDuration < 0 {
		return fmt.Errorf("Params.MaxBufferingDuration must be >= 0; got %s", p.MaxBufferingDuration)
	}
	return nil
}

const (
	sizerNone      int32 = 0
	sizerPrimitive int32 = 1
)

// codecCache keeps a per-value-type ElementEncoder/Decoder pair.
type codecCache struct {
	once sync.Once
	enc  beam.ElementEncoder
	dec  beam.ElementDecoder
}

View on GitHub (pinned to 12126d8942)