JuliusBrussee/caveman · error

cacheengine: cumulative token count overflow

Error message

cacheengine: cumulative token count overflow

What it means

Thrown by breakpointCandidates when adding segment.Tokens to the running cumulativeTokens total would overflow int. It is a hard stop before the cumulative count corrupts breakpoint token math.

Source

Thrown at cacheengine/engine.go:369

	var lengths [8]byte
	binary.BigEndian.PutUint32(lengths[:4], uint32(len(name)))
	binary.BigEndian.PutUint32(lengths[4:], uint32(len(content)))
	dst = append(dst, lengths[:]...)
	dst = append(dst, name...)
	return append(dst, content...)
}

func breakpointCandidates(segments []Segment, defaultCalls int, profile Profile) ([]Breakpoint, bool, bool, error) {
	var candidates []Breakpoint
	var prefix []byte
	cumulativeTokens := 0
	previousCalls := math.MaxInt
	belowMinimum := false
	negative := false
	for index, segment := range segments {
		prefix = appendFrame(prefix, segment.Name, segment.Content)
		if segment.Tokens > math.MaxInt-cumulativeTokens {
			return nil, false, false, errors.New("cacheengine: cumulative token count overflow")
		}
		cumulativeTokens += segment.Tokens
		calls := segment.ExpectedCalls
		if calls == 0 {
			calls = defaultCalls
		}
		if calls > previousCalls {
			return nil, false, false, errors.New("cacheengine: longer prefix cannot have higher expected reuse")
		}
		previousCalls = calls
		if calls < 2 {
			continue
		}
		if cumulativeTokens > 0 && cumulativeTokens < profile.MinPrefixTokens {
			belowMinimum = true
			continue
		}
		net := 0.0

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Validate each segment's Tokens is a plausible small number (< 10^9) before planning
2. Rebuild/run on a 64-bit target if you are on 386/arm and totals legitimately approach 2^31
3. Fix the tokenizer if it emits absurd counts for pathological input

Example fix

// before
segments := []cacheengine.Segment{{Name: "a", Stable: true, Cacheable: true, Content: b, Tokens: math.MaxInt}}

// after
segments := []cacheengine.Segment{{Name: "a", Stable: true, Cacheable: true, Content: b, Tokens: 120000}}

var total int
for _, s := range segs {
    if s.Tokens < 0 || s.Tokens > 1<<40 { return errors.New("implausible token count") }
    total += s.Tokens
    if total < 0 { return errors.New("token total overflow") }
}

// n/a

When it happens

Trigger: A segment list whose summed Tokens exceeds math.MaxInt (~9.2e18 on 64-bit, ~2.1e9 on 32-bit builds); on 32-bit targets, token counts in the low billions are enough to trigger it.

Common situations: Running the engine on a 32-bit architecture (GOARCH=386/arm) with large token counts; a tokenizer returning garbage (huge counts) for adversarial input; unit tests with MaxInt-valued token values to probe overflow behavior.

Related errors

• cacheengine: negative segment measurement
• cacheengine: cache economics overflow
• cachebench: replay token summary overflow
• cacheengine: invalid partition key
• cacheengine: negative traffic expectation

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/d33c202147a5dc3b. Report an issue: GitHub.