{"record":{"id":"3d48b730366c3d5e","repo":"apache/beam","slug":"capacity-must-be-a-positive-integer-got-v","errorCode":null,"errorMessage":"capacity must be a positive integer, got %v","messagePattern":"capacity must be a positive integer, got (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"sdks/go/pkg/beam/core/runtime/harness/statecache/statecache.go","lineNumber":77,"sourceCode":"\tenabled     bool\n\tmu          sync.Mutex\n\tcache       map[cacheKey]exec.ReStream\n\tidsToTokens map[string]token\n\tvalidTokens map[cacheToken]int8 // Maps tokens to active bundle counts\n\tmetrics     CacheMetrics\n}\n\n// CacheMetrics stores metrics for the cache across a pipeline run.\ntype CacheMetrics struct {\n\tHits, Misses, Evictions, InUseEvictions, ReStreamErrors int64\n}\n\n// Init makes the cache map and the map of IDs to cache tokens for the\n// SideInputCache. Should only be called once. Returns an error for\n// non-positive capacities.\nfunc (c *SideInputCache) Init(cap int) error {\n\tif cap < 0 {\n\t\treturn errors.Errorf(\"capacity must be a positive integer, got %v\", cap)\n\t}\n\tc.mu.Lock()\n\tdefer c.mu.Unlock()\n\tif cap == 0 {\n\t\tc.enabled = false\n\t\treturn nil\n\t}\n\tc.cache = make(map[cacheKey]exec.ReStream, cap)\n\tc.idsToTokens = make(map[string]token)\n\tc.validTokens = make(map[cacheToken]int8)\n\tc.capacity = cap\n\tc.metrics = CacheMetrics{}\n\tc.enabled = true\n\treturn nil\n}\n\n// SetValidTokens clears the list of valid tokens then sets new ones, also updating the mapping of\n// transform and side input IDs to cache tokens in the process. Should be called at the start of every","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/go/pkg/beam/core/runtime/harness/statecache/statecache.go#L59-L95","documentation":"SideInputCache.Init(cap) prepares the side-input cache and its ID-to-token map. It returns this error for negative capacities; cap == 0 legitimately disables the cache, and positive values enable it. The message text says \"must be a positive integer\" but the guard checks cap < 0, so the actual invalid case is a negative value. Callers should only pass 0 (disabled) or a positive size.","triggerScenarios":"Calling Init with a negative capacity, e.g. a cache size parsed from an env var or flag with a sign/format problem, or a caller passing -1 as an \"unlimited\" sentinel.","commonSituations":"Setting the harness cache size via environment/flags where a value like \"-1\" leaks through parsing; custom harness wiring passes a negative sentinel expecting unlimited; unit-test configs exercising bad-input cases (TestInit_Bad).","solutions":["Pass a positive integer capacity to enable caching, or 0 to explicitly disable it; never a negative value.","If the value comes from config/env/flag, validate it is >= 0 before calling Init.","Fix any sentinel usage: use 0 for disabled rather than -1.","If this fires in stock harness startup, check the beam_go_sdk container/harness options for a corrupted cache-size option.","Note the guard checks cap < 0 while the message says positive — zero is accepted as disabled; don't rely on the message text for the exact boundary."],"exampleFix":"// before\nvar cacheSize int = -1 // \"unlimited\" sentinel\ncache.Init(cacheSize)\n// after\ncacheSize := 0 // 0 disables the cache explicitly; use >0 to enable\nif cacheSize < 0 {\n    return fmt.Errorf(\"invalid state cache capacity %d\", cacheSize)\n}\nif err := cache.Init(cacheSize); err != nil {\n    return err\n}","handlingStrategy":"validation","validationCode":"func validCacheCapacity(n int) bool {\n    return n >= 0 // 0 disables the cache; positive enables it; negative is invalid\n}","typeGuard":null,"tryCatchPattern":"if err := cache.Init(capacity); err != nil {\n    if strings.Contains(err.Error(), \"capacity must be a positive integer\") {\n        return fmt.Errorf(\"bad state cache config: %v\", err)\n    }\n    return err\n}","preventionTips":["Never pass negative values to Init; use 0 to disable, positive to enable.","Validate cache-size flags/env values (>= 0) at config parse time.","Don't use -1 as an \"unlimited\" sentinel for this API.","When constructing harness options, clamp parsed sizes: if n < 0 { n = 0 }."],"tags":["beam-go","configuration","validation","cache"],"backgroundTag":"invalid-argument-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}