apache/beam · error

capacity of cache cannot be negative, got %v

Error message

capacity of cache cannot be negative, got %v

What it means

SideInputCacheCapacity configures the harness side-input cache size via a hook; a negative capacity is invalid since a cache cannot hold negative items. The function returns this error instead of enabling the hook, so callers must pass 0 (default/disabled) or a positive value.

Source

Thrown at sdks/go/pkg/beam/util/harnessopts/cache.go:37

package harnessopts

import (
	"fmt"
	"strconv"

	"github.com/apache/beam/sdks/v2/go/pkg/beam/core/util/hooks"
)

const (
	cacheCapacityHook = "beam:go:hook:sideinputcache:capacity"
)

// SideInputCacheCapacity accepts a desired capacity for the side input cache. A non-zero positive
// integer enables the cache (the capacity of the cache is 0 by default.) Cache use also requires runner
// support.
func SideInputCacheCapacity(capacity int64) error {
	if capacity < 0 {
		return fmt.Errorf("capacity of cache cannot be negative, got %v", capacity)
	}
	capString := strconv.FormatInt(capacity, 10)
	// The hook itself is defined in beam/core/runtime/harness/cache_hooks.go
	return hooks.EnableHook(cacheCapacityHook, capString)
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass 0 or a positive capacity to SideInputCacheCapacity
2. Check the error return and log/propagate it instead of ignoring
3. Sanitize flags/env values with a lower bound of 0 before calling
4. Treat 0 as 'disabled' rather than a negative sentinel

Example fix

// before
cap := flag.Int64("cache", -1, "size")
harnessopts.SideInputCacheCapacity(*cap) // errors when -1
// after
cap := flag.Int64("cache", 0, "size (0 disables)")
if *cap >= 0 {
    if err := harnessopts.SideInputCacheCapacity(*cap); err != nil { log.Fatal(err) }
}

if capacity < 0 {
    return errors.New("side input cache capacity must be >= 0")
}
if err := harnessopts.SideInputCacheCapacity(capacity); err != nil {
    return err
}

When it happens

Trigger: Calling harnessopts.SideInputCacheCapacity with a negative int64, typically from a parsed flag or env variable that used -1 as an 'unset' sentinel or was mis-parsed.

Common situations: Using -1 as an 'unset' sentinel value in worker options; config files with negative numbers; arithmetic overflow producing negatives.

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

• Expected weight to be > 0 for %s but received %d
• OnTimer function is defined for the DoFn but no TimerProvide
• internal: log message buffer closed
• side input closed
• empty pipeline

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