JuliusBrussee/caveman · error

trial compression replay exceeds %d-byte payload budget

Error message

trial compression replay exceeds %d-byte payload budget

What it means

During AnalyzeTrial's compression replay, the store accumulates the request_bytes of every captured payload for the trial and aborts as soon as any single payload is negative/oversized or the running total would exceed maxBytes (CAVE_TRIAL_REPLAY_MAX_BYTES, default 256 MiB, clamped back to the default if misconfigured). This is a resource guard: replay decompresses and transforms payloads in memory, so an unbounded trial could exhaust RAM.

Source

Thrown at proxy/internal/store/trial_store.go:552

		if recovery != nil {
			_ = recovery.Close()
		}
	}()
	var eng *engine.Engine
	var totalBytes int64
	var payloadCount, before, after, transformed int
	for rows.Next() {
		var p struct {
			raw                       []byte
			bytes                     int64
			provider, model, endpoint string
		}
		if err := rows.Scan(&p.raw, &p.bytes, &p.provider, &p.model, &p.endpoint); err != nil {
			return TrialMove{}, "", err
		}
		payloadCount++
		if p.bytes < 0 || p.bytes > maxBytes || totalBytes > maxBytes-p.bytes {
			return TrialMove{}, "", fmt.Errorf("trial compression replay exceeds %d-byte payload budget", maxBytes)
		}
		totalBytes += p.bytes
		adapter := replayAdapter(p.provider)
		if adapter == nil {
			continue
		}
		segments, reassemble, ok := adapter.ExtractCompressible(p.raw, providers.RequestMetadata{
			Provider: p.provider,
			Model:    p.model,
			Endpoint: p.endpoint,
		})
		if !ok || len(segments) == 0 {
			continue
		}
		if eng == nil {
			if err := os.MkdirAll(filepath.Dir(ccrPath), 0o700); err != nil {
				return TrialMove{}, "", err
			}

View on GitHub (pinned to 27d5a3981a)

Solutions

  1. Raise the budget for the analysis run: CAVE_TRIAL_REPLAY_MAX_BYTES=1073741824 caveman ... (confirm host RAM first).
  2. Start a fresh trial for the workload you actually want to analyze so captured payloads stay under the default budget.
  3. If the cap was deliberately lowered, re-check its value — values <= 0 fall back to the 256 MiB default, but a small positive value silently shrinks it.
  4. Inspect trial_payloads (SELECT SUM(request_bytes) ...) to see whether one giant request or sheer count is the cause.

Example fix

# before
export CAVE_TRIAL_REPLAY_MAX_BYTES=1048576  # 1 MiB, too small
caveman trial analyze

# after
export CAVE_TRIAL_REPLAY_MAX_BYTES=1073741824  # 1 GiB, sized to the trial
caveman trial analyze
Defensive patterns

Strategy: validation

Validate before calling

// Estimate before analyzing: sum captured payload bytes for the trial.
var total int64
s.DB().QueryRow(`SELECT COALESCE(SUM(request_bytes),0) FROM trial_payloads WHERE trial_id = ?`, trialID).Scan(&total)
const budget = int64(256 << 20) // mirror CAVE_TRIAL_REPLAY_MAX_BYTES default
if total > budget {
    log.Printf("trial captures %d bytes > %d budget; raising env or splitting trial", total, budget)
}

Try / catch

plan, err := s.AnalyzeTrial(trialID, ccrPath)
if err != nil {
    if strings.Contains(err.Error(), "payload budget") {
    // deterministic resource limit — raise the env cap deliberately or use a smaller trial; do not blind-retry
        return handleBudgetExceeded(trialID, err)
    }
    return err
}

Prevention

When it happens

Trigger: Analyzing a long-running trial whose captured requests sum past 256 MiB (e.g. hundreds of large-context Claude/OpenAI requests), or one single payload larger than the budget; alternatively setting CAVE_TRIAL_REPLAY_MAX_BYTES very low so even modest trials trip it.

Common situations: Long agent sessions with big system prompts and file contexts; lowering the env cap without realizing it applies to the cumulative sum; a corrupted row where request_bytes disagrees wildly with raw_request length.

Related errors

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