{"record":{"id":"567365a9a21b5039","repo":"apache/beam","slug":"start-sequence-number-must-be-greater-than-0","errorCode":null,"errorMessage":"start sequence number must be greater than 0","messagePattern":"start sequence number must be greater than 0","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"sdks/go/pkg/beam/io/natsio/read_option.go","lineNumber":22,"sourceCode":"// The ASF licenses this file to You under the Apache License, Version 2.0\n// (the \"License\"); you may not use this file except in compliance with\n// the License.  You may obtain a copy of the License at\n//\n//    http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage natsio\n\nimport \"errors\"\n\nvar (\n\terrInvalidFetchSize  = errors.New(\"fetch size must be greater than 0\")\n\terrInvalidStartSeqNo = errors.New(\"start sequence number must be greater than 0\")\n\terrInvalidEndSeqNo   = errors.New(\"end sequence number must be greater than 0\")\n)\n\ntype readOption struct {\n\tCredsFile  string\n\tTimePolicy timePolicy\n\tFetchSize  int\n\tStartSeqNo int64\n\tEndSeqNo   int64\n}\n\n// ReadOptionFn is a function that can be passed to Read to configure options for reading\n// from NATS.\ntype ReadOptionFn func(option *readOption) error\n\n// ReadUserCredentials sets the user credentials when connecting to NATS.\nfunc ReadUserCredentials(credsFile string) ReadOptionFn {\n\treturn func(o *readOption) error {","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/go/pkg/beam/io/natsio/read_option.go#L4-L40","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass a sequence number >= 1, e.g. natsio.WithStartSeqNo(1) to start from the first message.","Treat an unset/0 stored cursor as 'start from beginning' and substitute 1 before calling WithStartSeqNo.","Validate the configured value before building options."],"exampleFix":"// before\nopts = append(opts, natsio.WithStartSeqNo(cursor)) // cursor = 0 when no checkpoint exists\n// after\nif cursor <= 0 {\n    cursor = 1\n}\nopts = append(opts, natsio.WithStartSeqNo(cursor))","handlingStrategy":"validation","validationCode":"if startSeq <= 0 {\n    startSeq = 1 // NATS sequences are 1-based\n}\nopts = append(opts, natsio.WithStartSeqNo(startSeq))","typeGuard":null,"tryCatchPattern":"if err := applyReadOptions(opts...); err != nil {\n    if errors.Is(err, errInvalidStartSeqNo) {\n        return fmt.Errorf(\"start sequence must be >= 1: %w\", err)\n    }\n    return err\n}","preventionTips":["Normalize missing cursor checkpoints to sequence 1, not 0.","Remember NATS sequence numbers start at 1; encode that in cursor storage.","Validate start <= end when both are configured."],"tags":["go","apache-beam","nats","sequence-number","config-validation"],"backgroundTag":"invalid-config-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}