What causes "fetch size must be greater than 0" in apache/beam?

Pass a strictly positive size, e.g. natsio.WithFetchSize(100).

fetch size must be greater than 0

Error message

fetch size must be greater than 0

What it means

errInvalidFetchSize is a sentinel error in the Beam NATS connector returned by the WithFetchSize read option when the requested fetch size is zero or negative. A non-positive fetch size cannot bound how many messages to pull per batch, so the option application fails fast.

Source

Thrown at sdks/go/pkg/beam/io/natsio/read_option.go:21

// this work for additional information regarding copyright ownership.
// The ASF licenses this file to You under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with
// the License.  You may obtain a copy of the License at
//
//    http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package natsio

import "errors"

var (
	errInvalidFetchSize  = errors.New("fetch size must be greater than 0")
	errInvalidStartSeqNo = errors.New("start sequence number must be greater than 0")
	errInvalidEndSeqNo   = errors.New("end sequence number must be greater than 0")
)

type readOption struct {
	CredsFile  string
	TimePolicy timePolicy
	FetchSize  int
	StartSeqNo int64
	EndSeqNo   int64
}

// ReadOptionFn is a function that can be passed to Read to configure options for reading
// from NATS.
type ReadOptionFn func(option *readOption) error

// ReadUserCredentials sets the user credentials when connecting to NATS.
func ReadUserCredentials(credsFile string) ReadOptionFn {

View on GitHub (pinned to 12126d8942)

Solutions

Pass a strictly positive size, e.g. natsio.WithFetchSize(100).
Validate or default the value before constructing options: if size <= 0 { size = defaultFetchSize }.
Verify the config source actually populated the value instead of leaving it at Go's zero value.

Example fix

// before
opts = append(opts, natsio.WithFetchSize(fetchSize)) // fetchSize = 0
// after
if fetchSize <= 0 {
    fetchSize = 100
}
opts = append(opts, natsio.WithFetchSize(fetchSize))

Defensive patterns

Strategy: validation

Validate before calling

if fetchSize <= 0 {
    fetchSize = 100
}
opts = append(opts, natsio.WithFetchSize(fetchSize))

Try / catch

if err := applyReadOptions(opts...); err != nil {
    if errors.Is(err, errInvalidFetchSize) {
        return fmt.Errorf("configure a positive fetch size: %w", err)
    }
    return err
}

Prevention

Never rely on Go zero values for option ints; set defaults in the option constructor.
Validate NATS read parameters together in one config-loading function.
Document that fetch size is 1-based positive in your wrapper API.

When it happens

Trigger: Passing natsio.WithFetchSize(0) or a negative int into the read options of a NATS read transform; the error is returned when the option function is applied to readOption.

Common situations: Fetch size configured via flags/env with zero default; int overflow or failed parse yielding 0; copy-paste between options where the wrong variable was passed.

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/d62572d979604da1. Report an issue: GitHub.