What causes "max partitions must be greater than 0" in apache/beam?

Pass a positive int64, e.g. WithMaxPartitions(1024)

max partitions must be greater than 0

Error message

max partitions must be greater than 0

What it means

This error comes from the Spanner IO query option helper WithMaxPartitions, which configures the maximum number of partitions a batched Spanner query read is split into. The library validates the supplied value and rejects it when it is zero or negative, because Spanner requires at least one partition to execute a batched read. It is a fail-fast guard against an unusable configuration.

Solutions

Pass a positive int64, e.g. WithMaxPartitions(1024)
Validate/parse the source config before constructing options and substitute a sane default (e.g. >= 1) when unset

Example fix

// before
opts, err := spannerio.WithMaxPartitions(maxPartitions) // maxPartitions = 0 from unset flag
// after
if maxPartitions <= 0 {
    maxPartitions = 1024
}
opts, err := spannerio.WithMaxPartitions(maxPartitions)

Defensive patterns

Strategy: validation

Validate before calling

func validMaxPartitions(n int64) bool { return n > 0 }

Prevention

Default maxPartitions to a positive constant when the config value is unset
Parse numeric flags with strconv.ParseInt and check the error and sign before use

When it happens

Trigger: Calling beam/io/spannerio WithMaxPartitions(maxPartitions) with a value <= 0, e.g. a zero default from an unset config variable, a negative value from a misparsed CLI flag, or a computed size that divided down to 0.

Common situations: Developers wiring the max partitions value from environment variables, flags, or pipeline options without validating numeric parsing; empty/absent config yields 0 which fails here.

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

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

Appendix: source

Thrown at sdks/go/pkg/beam/io/spannerio/query_options.go:65

	}

	return opts
}

// WithBatching sets whether we will use a batched reader. Batching is set to true by default, disable it when the
// underlying query is not root-partitionable.
func WithBatching(batching bool) QueryOptionFn {
	return func(opts *queryOptions) error {
		opts.Batching = batching
		return nil
	}
}

// WithMaxPartitions sets the maximum number of Partitions to split the query into when batched reading.
func WithMaxPartitions(maxPartitions int64) QueryOptionFn {
	return func(opts *queryOptions) error {
		if maxPartitions <= 0 {
			return errors.New("max partitions must be greater than 0")
		}

		opts.MaxPartitions = maxPartitions
		return nil
	}
}

// WithTimestampBound sets the TimestampBound to use when doing batched reads.
func WithTimestampBound(timestampBound spanner.TimestampBound) QueryOptionFn {
	return func(opts *queryOptions) error {
		opts.TimestampBound = timestampBound
		return nil
	}
}

View on GitHub (pinned to 12126d8942)