apache/beam · error

natsio.Read: invalid option: %v

Error message

natsio.Read: invalid option: %v

What it means

natsio.Read panics when an option function passed to it returns an error, meaning an invalid ReadOption was supplied. This library validates options eagerly at pipeline-construction time and treats a bad option as a programmer error, so it panics instead of returning an error. The panic happens before any distributed work starts.

Source

Thrown at sdks/go/pkg/beam/io/natsio/read.go:89

func Read(
	s beam.Scope,
	uri string,
	stream string,
	subject string,
	opts ...ReadOptionFn,
) beam.PCollection {
	s = s.Scope("natsio.Read")

	option := &readOption{
		TimePolicy: processingTimePolicy,
		FetchSize:  defaultFetchSize,
		StartSeqNo: defaultStartSeqNo,
		EndSeqNo:   defaultEndSeqNo,
	}

	for _, opt := range opts {
		if err := opt(option); err != nil {
			panic(fmt.Sprintf("natsio.Read: invalid option: %v", err))
		}
	}

	imp := beam.Impulse(s)
	return beam.ParDo(s, newReadFn(uri, stream, subject, option), imp)
}

type readFn struct {
	natsFn
	Stream      string
	Subject     string
	TimePolicy  timePolicy
	FetchSize   int
	StartSeqNo  int64
	EndSeqNo    int64
	timestampFn timestampFn
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Check which option in the variadic list returns an error; the wrapped error text is included in the panic message.
2. Fix the option's parameters (e.g. valid sequence-number ranges) at the call site.
3. Only pass options produced by this package's exported option constructors.
4. If the panic is undesirable, validate options yourself by invoking opt(option) and checking err before calling Read.

Example fix

// before
beam.ParDo(s, newReadFn(uri, stream, subject, option), imp) // option built with bad value
// after
opt := natsio.WithStartSeqNo(1) // use exported constructors with valid values
if err := opt(option); err != nil {
    return fmt.Errorf("bad nats option: %w", err)
}
natsio.Read(s, uri, stream, subject, opt)

for _, opt := range opts {
    if err := opt(option); err != nil {
        return fmt.Errorf("invalid natsio option: %w", err)
    }
}

defer func() {
    if r := recover(); r != nil {
        if s, ok := r.(string); ok && strings.Contains(s, "natsio.Read: invalid option") {
            // handle
        } else { panic(r) }
    }
}()

When it happens

Trigger: Calling natsio.Read(s, uri, stream, subject, someInvalidOption()) where an option function (e.g. one built with wrong bounds, negative values, or a misused option constructor) returns a non-nil error from opt(option).

Common situations: Passing an option constructed for a different io connector into natsio.Read; misconfiguring sequence numbers (StartSeqNo > EndSeqNo); copying example code and editing an option helper so it returns an error.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• unsupported time policy
• spannerio.Query: invalid option: %v
• 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/55edd96d6bc383b8. Report an issue: GitHub.