JuliusBrussee/caveman · error

cacheengine: negative traffic expectation

Error message

cacheengine: negative traffic expectation

What it means

Thrown by validatePlanRequest when request.ExpectedCalls or request.ExpectedRequestsPerMinute is negative. These fields size the cache plan (breakpoint economics, key sharding); negative traffic estimates would produce nonsensical plans.

Source

Thrown at cacheengine/engine.go:279

		PrefixSHA256:   result.PrefixSHA256,
		EconomicsBasis: economicsBasis,
		KeyShardCount:  1,
		Warnings:       warnings,
	}, nil
}

func validatePlanRequest(request PlanRequest) error {
	if !validIdentity(request.Scope, 4096, false) {
		return errors.New("cacheengine: invalid scope")
	}
	if !validIdentity(request.Epoch, 4096, false) {
		return errors.New("cacheengine: invalid epoch")
	}
	if !validIdentity(request.PartitionKey, 4096, true) {
		return errors.New("cacheengine: invalid partition key")
	}
	if request.ExpectedCalls < 0 || request.ExpectedRequestsPerMinute < 0 {
		return errors.New("cacheengine: negative traffic expectation")
	}
	profile := normalizedProfile(request.Profile)
	if !validIdentity(profile.ID, 256, false) || !validIdentity(profile.Provider, 64, true) || !validIdentity(profile.OptimizerID, 256, true) {
		return errors.New("cacheengine: invalid profile identity")
	}
	if profile.Mode != ModeUnsupported && profile.Mode != ModeImplicit && profile.Mode != ModeAffinity && profile.Mode != ModeExplicit {
		return fmt.Errorf("cacheengine: unknown mode %q", profile.Mode)
	}
	if profile.Mode != ModeUnsupported {
		if profile.MaxBreakpoints <= 0 || profile.MinPrefixTokens < 0 || profile.MaxRPMPerKey < 0 || profile.TTL < 0 {
			return errors.New("cacheengine: invalid cache thresholds")
		}
		switch profile.Attribution {
		case AttributionNone, AttributionOrganic, AttributionAffinity, AttributionCausal:
		default:
			return fmt.Errorf("cacheengine: unknown attribution %q", profile.Attribution)
		}
		if profile.EconomicsKnown && (!finiteNonNegative(profile.WriteMultiplier) || !finiteNonNegative(profile.ReadMultiplier)) {

View on GitHub (pinned to 27d5a3981a)

Solutions

  1. Clamp or recompute the estimate so both fields are >= 0 before calling Plan
  2. Use 0 (not -1) to mean 'no estimate'; the engine substitutes defaults such as defaultCalls
  3. Audit where the negative value originates if it comes from your own metrics pipeline

Example fix

// before
req.ExpectedCalls = currentCalls - previousCalls // can go negative

// after
if d := currentCalls - previousCalls; d > 0 {
    req.ExpectedCalls = d
} else {
    req.ExpectedCalls = 0
}
Defensive patterns

Strategy: validation

Validate before calling

if req.ExpectedCalls < 0 || req.ExpectedRequestsPerMinute < 0 { req.ExpectedCalls, req.ExpectedRequestsPerMinute = 0, 0 }

Type guard

func nonNegativeTraffic(req cacheengine.PlanRequest) bool { return req.ExpectedCalls >= 0 && req.ExpectedRequestsPerMinute >= 0 }

Try / catch

if err := engine.Plan(req); err != nil && strings.Contains(err.Error(), "negative traffic") { logMetricsBug(); return err }

Prevention

When it happens

Trigger: Calling Plan with ExpectedCalls < 0 or ExpectedRequestsPerMinute < 0, e.g. after a subtraction or a delta computation that underflows, or by confusing 'unknown' (0) with 'none' (-1).

Common situations: Computing expected calls as thisPeriod - lastPeriod and going negative during a traffic drop; passing -1 as a 'not set' sentinel; unmarshalling a negative value from user-supplied JSON config.

Related errors

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