apache/beam · error

start sequence number must be greater than 0

Error message

start sequence number must be greater than 0

What it means

errInvalidStartSeqNo is a sentinel error returned by the WithStartSeqNo NATS read option when the starting sequence number is zero or negative. NATS stream sequence numbers are 1-based, so a start sequence must be >= 1 to be meaningful.

Source

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

// 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 {
	return func(o *readOption) error {

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass a sequence number >= 1, e.g. natsio.WithStartSeqNo(1) to start from the first message.
2. Treat an unset/0 stored cursor as 'start from beginning' and substitute 1 before calling WithStartSeqNo.
3. Validate the configured value before building options.

Example fix

// before
opts = append(opts, natsio.WithStartSeqNo(cursor)) // cursor = 0 when no checkpoint exists
// after
if cursor <= 0 {
    cursor = 1
}
opts = append(opts, natsio.WithStartSeqNo(cursor))

if startSeq <= 0 {
    startSeq = 1 // NATS sequences are 1-based
}
opts = append(opts, natsio.WithStartSeqNo(startSeq))

if err := applyReadOptions(opts...); err != nil {
    if errors.Is(err, errInvalidStartSeqNo) {
        return fmt.Errorf("start sequence must be >= 1: %w", err)
    }
    return err
}

When it happens

Trigger: Passing natsio.WithStartSeqNo(0) or a negative value into the read options; typically when the value is left as Go's zero-value int from an unset config.

Common situations: Replaying from a sequence number tracked in a database that had no entry (0); missing pipeline option defaulting to 0; confusion that 0 means 'beginning' when the library requires >= 1.

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

• end sequence number must be greater than 0
• fetch size must be greater than 0
• bundle size must be greater than 0
• batch size must be greater than 0
• natsio.Read: invalid option: %v

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